From: Oliver Schmidt Date: Sun, 24 Mar 2013 23:50:52 +0000 (+0100) Subject: No linuxdoc here. Documenation is to be maintained as HTML in branch 'gh-pages'. X-Git-Tag: V2.14~82 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=fcea8951f1dc51cce28cabfc9cfec760a341118a;p=cc65 No linuxdoc here. Documenation is to be maintained as HTML in branch 'gh-pages'. --- diff --git a/doc/BUGS b/doc/BUGS deleted file mode 100644 index 63a3253df..000000000 --- a/doc/BUGS +++ /dev/null @@ -1,8 +0,0 @@ -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. diff --git a/doc/CREDITS b/doc/CREDITS deleted file mode 100644 index d32dd7966..000000000 --- a/doc/CREDITS +++ /dev/null @@ -1,160 +0,0 @@ - -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 - - 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 did the Apple 2 port and found at least one serious error in the - C library while doing so. - - * Christian Groessler - Mark Keates - Freddy Offenga - David Lloyd - - 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 rewrote the random number generator. - - * Maciej Witkowiak - - Maciej wrote the GEOS support libraries for cc65. - - * Eric Au - - 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 - - Miroc contributed Makefile additions, docs and patches to compile cc65 - cleanly under OS/2 using the EMX toolkit. - - * Marc 'BlackJack' Rintsch - - Marc wrote and contributed BASIC compatible file I/O routines for the - Commodore machines. - - * Groepaz - - 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 contributed the VIC20 port. - - * Michael Klein - - for the Debian support files. - - * Greg King - - reported quite some bugs and helped with lots of code and suggestions. - - * MagerValp - - 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 - - for the zlib routines, lots of bug reports, code snippets and - suggestions. - - * Josef Soucek - - 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 - - Stefan contributed several code snippets for the C64 and Apple ][. - - * Peter Trauner - - 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 and Shawn - Jefferson who built on this foundation. - - * Oliver Schmidt ... - - ... for quite some Apple ][ contributions. - - - -Thanks to - - da Blondie - Adam Dunkels - Bill Craig - C. N. Wong - Carsten Strotmann - Chris Ward - Dagan Galarneau - Darrell Krulce - Dennis Lin - Eric Bacher - Gábor Lénárt - Ingo Korb - Jacek Jozwiak - Jaleco - Jari Tuominen - Jesse Beach - Joerg Schwedes - John Weidman - Jonathan Wright - Kevin Schuetz - Mark Nasgowitz - Peter Karlsson - Peter Wendrich - Robert R. Wal - Shawn Jefferson - Stefan Andree - Stephan Lesch - Tim Vanderhoek - Todd Elliott - Johan Kotlinski - -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. - - diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 8e42729d5..000000000 --- a/doc/Makefile +++ /dev/null @@ -1,135 +0,0 @@ -# -*- 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 $< diff --git a/doc/apple2.sgml b/doc/apple2.sgml deleted file mode 100644 index fb6dda7fe..000000000 --- a/doc/apple2.sgml +++ /dev/null @@ -1,544 +0,0 @@ - - -
- -Apple ][ specific information for cc65 -<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> -<date>2009-10-07 - -<abstract> -An overview over the Apple ][ runtime system as it is -implemented for the cc65 C compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the Apple ][ runtime system -as it comes with the cc65 C compiler. It describes the memory layout, -Apple ][ specific header files, available drivers, and any -pitfalls specific to that platform. - -Please note that Apple ][ specific functions are just mentioned -here, they are described in detail in the separate <htmlurl url="funcref.html" -name="function reference">. Even functions marked as "platform dependent" may -be available on more than one platform. Please see the function reference for -more information. - - - -<sect>Binary format<p> - -The standard binary file format generated by the linker for the -Apple ][ target is a binary program with a 4 byte DOS 3.3 header -containing the load address and load length. The default load address is -$803. - -<bf/AppleCommander 1.3.5/ or later (available at <url -url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/ -that allows to put binary files with a DOS 3.3 header onto disk images -containing DOS 3.3 as well as ProDOS 8. - -For ProDOS 8 system programs the load address is fixed to $2000 so there -is no need for a header. Thus the linker configuration -<htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> for those programs -omits the DOS 3.3 header. The right AppleCommander option to put system files -without a header on a ProDOS 8 disk image is <tt/-p/. - - -<sect>Memory layout<p> - -In the standard setup, cc65 generated programs use the memory from -$803 to $95FF, so 35.5 KB of RAM are available. - -Special locations: - -<descrip> - - <tag/Stack/ - The C runtime stack is located at HIMEM and grows downwards, regardless of - how your linker config file is setup. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - -While running <tt/main()/ the Language Card bank 2 is enabled for read access. -However while running module constructors/destructors the Language Card is disabled. - -Enabling the Language Card allows to use it as additional memory for cc65 -generated code. However code is never automatically placed there. Rather code -needs to be explicitly placed in the Language Card either per file by compiling -with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma -code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the -cc65 runtime system takes care of actually moving the code into the Language -Card. - -The amount of memory available in the Language Card for generated code depends -on the chosen <htmlurl url="apple2-4.html" name="linker configuration">. - - - -<sect>Linker configurations<p> - -The ld65 linker comes with a builtin config file for the Apple ][, -which is used via <tt/-t apple2/ (and displayed via <tt/--dump-config apple2/). -The apple2 package comes with additional secondary linker config files, which -are used via <tt/-C <configfile>/. - - -<sect1>builtin config file<p> - -Default configuration optimized for a binary program running on ProDOS 8 with -BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card -bank 2 memory from $D400 to $DFFF. - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $803 to $95FF (35.5 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D400 to $DFFF (3 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Variable (default: $803) - - <tag><tt/HEADER:/ Binary file header</tag> - DOS 3.3 header (address and length) - -</descrip><p> - - -<sect1><tt/apple2-dos33.cfg/<p> - -Configuration optimized for a binary program running on DOS 3.3. A plain -vanilla DOS 3.3 doesn't make use of the Language Card at all. - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $803 to $95FF (35.5 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D000 to $FFFF (12 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Variable (default: $803) - - <tag><tt/HEADER:/ Binary file header</tag> - DOS 3.3 header (address and length) - -</descrip><p> - - -<sect1><tt/apple2-system.cfg/<p> - -Configuration for a system program running on ProDOS 8. - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $2000 to $BEFF (39.75 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D400 to $DFFF (3 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Fixed ($2000) - - <tag><tt/HEADER:/ Binary file header</tag> - None - -</descrip><p> - - -<sect1><tt/apple2-loader.cfg/<p> - -Configuration optimized for a binary program running on ProDOS 8 without -BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an -Apple ][ ProDOS 8 loader for cc65 programs/, which is available -in the cc65 User Contributions section. - -A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but -isn't tied to the start address $2000. Thus with the default start -address $800 the main memory area is increased by 6 KB. - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $800 to $BEFF (45.75 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D400 to $DFFF (3 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Variable (default: $800) - - <tag><tt/HEADER:/ Binary file header</tag> - DOS 3.3 header (address and length) - -</descrip><p> - - -<sect1><tt/apple2-reboot.cfg/<p> - -Configuration optimized for a binary program running on ProDOS 8 without -BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an -Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together -with the function <tt/rebootafterexit()/. - -If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather -reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of -the Language Card bank 2 at all. - -This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine! - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $800 to $BEFF (45.75 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D000 to $DFFF (4 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Variable (default: $800) - - <tag><tt/HEADER:/ Binary file header</tag> - DOS 3.3 header (address and length) - -</descrip><p> - - - -<sect>ProDOS 8 system programs<p> - -ProDOS 8 system programs are always loaded to the start address $2000. -For cc65 programs this means that the 6 KB from $800 to $2000 are -by default unused. There are however several options to make use of that memory -range. - - -<sect1>LOADER.SYSTEM<p> - -The easiest (and for really large programs in fact the only) way to have a cc65 -program use the memory from $800 to $2000 is to link it as binary -(as opposed to system) program using the linker configuration -<htmlurl url="apple2-4.html#ss4.4" name="apple2-loader.cfg"> with start address -$800 and load it with <bf/LOADER.SYSTEM - an Apple ][ -ProDOS 8 loader for cc65 programs/. The program then works like a system program -(i.e. quits to the ProDOS dispatcher). - -Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the -program to load under name <program>.SYSTEM as a system program. For -example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. - - -<sect1>Heap<p> - -If the cc65 program can be successfully linked as system program using the linker -configuration <htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> but -uses the heap either explicitly or implicitly (i.e. by loading a driver) then -the memory from $800 to $2000 can be added to the heap by calling -<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/. - - -<sect1>ProDOS 8 I/O buffers<p> - -ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default -these buffers are allocated by the cc65 runtime system on the heap using -<tt/posix_memalign()/. While this is generally the best solution it means quite -some overhead for (especially rather small) cc65 programs which do open files -but don't make use of the heap otherwise. - -The apple2 package comes with the alternative ProDOS 8 I/O buffer allocation -module <tt/apple2-iobuf-0800.o/ which uses the memory between $800 and -the program start address for the 1 KB I/O buffers. For system programs (with -start address $2000) this results in up to 6 I/O buffers and thus up to 6 -concurrently open files. - -While using <tt/_heapadd()/ as described in the section above together with the -default I/O buffer allocation basically yields the same placement of I/O buffers -in memory the primary benefit of <tt/apple2-iobuf-0800.o/ is a reduction in code -size - and thus program file size - of more than 1400 bytes. - -Using <tt/apple2-iobuf-0800.o/ is as simple as placing it on the linker command -line like this: - -<tscreen><verb> -cl65 -t apple2 -C apple2-system.cfg myprog.c apple2-iobuf-0800.o -</verb></tscreen> - - - -<sect>Platform specific header files<p> - -Programs containing Apple ][ specific code may use the -<tt/apple2.h/ header file. - - -<sect1>Apple ][ specific functions<p> - -The functions listed below are special for the Apple ][. See -the <htmlurl url="funcref.html" name="function reference"> for declaration and -usage. - -<itemize> -<item>_auxtype -<item>_dos_type -<item>_filetype -<item>get_ostype -<item>rebootafterexit -<item>ser_apple2_slot -<item>tgi_apple2_mix -</itemize> - - -<sect1>Hardware access<p> - -There's currently no support for direct hardware access. This does not mean -you cannot do it, it just means that there's no help. - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -<descrip> - - <tag><tt/a2.lo.tgi (apple2_40_48_16)/</tag> - This driver features a resolution of 40×48 with 16 colors. - - The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The - function clears the corresponding area at the bottom of the screen. - - <tag><tt/a2.hi.tgi (apple2_280_192_8)/</tag> - This driver features a resolution of 280×192 with 8 colors and two - hires pages. Note that programs using this driver will have to be linked - with <tt/--start-addr $4000/ to reserve the first hires page or with - <tt/--start-addr $6000/ to reserve both hires pages. - - The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The - function doesn't clear the corresponding area at the bottom of the screen. - - In memory constrained situations the memory from $803 to $1FFF - can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/ - at the beginning of <tt/main()/. Doing so is beneficial even if the program - doesn't use the the heap explicitly because loading the driver (and in fact - already opening the driver file) uses the heap implicitly. - -</descrip><p> - - -<sect1>Extended memory drivers<p> - -<descrip> - - <tag><tt/a2.auxmem.emd (apple2_auxmem)/</tag> - Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended - 80-Column Text Card. - - Note that this driver doesn't check for the actual existence of the memory - and that it doesn't check for ProDOS 8 RAM disk content! - -</descrip><p> - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/a2.stdjoy.joy (apple2_stdjoy)/</tag> - Supports up to two standard analog joysticks connected to the game port of - the Apple ][. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -<descrip> - - <tag><tt/a2.stdmou.mou (apple2_stdmou)/</tag> - Driver for the AppleMouse II Card. Searches all Apple II slots - for an AppleMouse II Card compatible firmware. The default bounding - box is [0..279,0..191]. - - Programs using this driver will have to be linked with <tt/--start-addr $4000/ - to reserve the first hires page if they are intended to run on an - Apple ][ (in contrast to an Apple //e) because the - AppleMouse II Card firmware writes to the hires page when initializing - on that machine. - - Note that the Apple ][ default mouse callbacks support text - mode only. - -</descrip><p> - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/a2.ssc.ser (apple2_ssc)/</tag> - Driver for the Apple II Super Serial Card. Supports up to 19200 baud, - hardware flow control (RTS/CTS) and interrupt driven receives. Note - that because of the peculiarities of the 6551 chip transmits are not - interrupt driven, and the transceiver blocks if the receiver asserts - flow control because of a full buffer. - - The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to - <tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/ - succeeds for all Apple II slots, but <tt/ser_open()/ fails with - <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot. - -</descrip><p> - - - -<sect>Limitations<p> - - -<sect1>DOS 3.3<p> - -Although the standard binaries generated by the linker for the Apple ][ -generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with -BASIC.SYSTEM) there are some limitations for DOS 3.3: - -<descrip> - - <tag>Disk File I/O</tag> - There's no disk file I/O support. Any attempt to use it yields an error with - <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers - are in general not functional as they depend on disk file I/O. However they - may be converted to statically linked drivers using the co65 object-file - converter. - - <tag/Interrupts/ - There's no <tt/interruptor/ support. Any attempt to use it yields the message - 'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that - <tt/a2.stdmou.mou/ and <tt/a2.ssc.ser/ are not functional as they depend on - interrupts. - -</descrip><p> - - -<sect1>Direct console I/O<p> - -<descrip> - - <tag/Color/ - The Apple ][ has no color text mode. Therefore the functions - <htmlurl url="funcref-205.html" name="textcolor()">, - <htmlurl url="funcref-68.html" name="bgcolor()"> and - <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. - - <tag/Cursor/ - The Apple ][ has no hardware cursor. Therefore the function - <htmlurl url="funcref-88.html" name="cursor()"> has no effect. - -</descrip><p> - - - -<sect>Other hints<p> - - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not -supported by BASIC, the following syntax was chosen: - -<tscreen><verb> -]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 -</verb></tscreen> - -<enum> -<item>Arguments are separated by spaces. -<item>Arguments may be quoted. -<item>Leading and trailing spaces around an argument are ignored. Spaces within - a quoted argument are allowed. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 10 arguments (including the program name) are - supported. -</enum> - - -<sect1>Interrupts<p> - -The runtime for the Apple ][ uses routines marked as -<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be -written as simple machine language subroutines and will be called -automatically by the interrupt handler code when they are linked into a -program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl -url="ca65.html" name="assembler manual">. - - -<sect1>DIO<p> - -<descrip> - - <tag/Drive ID/ - The function <htmlurl url="dio-1.html" name="dio_open()"> has the single - parameter <tt/device/ to identify the device to be opened. Therefore an - Apple II slot and drive pair is mapped to that <tt/device/ according - to the formula - - <tscreen> - device = slot + (drive - 1) * 8 - </tscreen> - - so that for example slot 6 drive 2 is mapped to <tt/device/ 14. - - <tag/Sector count/ - The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns - the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8 - disk it simply always returns 280 (which is only correct for a 140 KB disk). - This condition is indicated by the <tt/_oserror/ value 82. - -</descrip><p> - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml deleted file mode 100644 index 667ae9ec7..000000000 --- a/doc/apple2enh.sgml +++ /dev/null @@ -1,550 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Enhanced Apple //e specific information for cc65 -<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> -<date>2009-10-07 - -<abstract> -An overview over the enhanced Apple //e runtime system as it is -implemented for the cc65 C compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the enhanced Apple //e runtime system -as it comes with the cc65 C compiler. It describes the memory layout, -enhanced Apple //e specific header files, available drivers, and any -pitfalls specific to that platform. - -Please note that enhanced Apple //e specific functions are just mentioned -here, they are described in detail in the separate <htmlurl url="funcref.html" -name="function reference">. Even functions marked as "platform dependent" may -be available on more than one platform. Please see the function reference for -more information. - - - -<sect>Binary format<p> - -The standard binary file format generated by the linker for the -enhanced Apple //e target is a binary program with a 4 byte DOS 3.3 header -containing the load address and load length. The default load address is -$803. - -<bf/AppleCommander 1.3.5/ or later (available at <url -url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/ -that allows to put binary files with a DOS 3.3 header onto disk images -containing DOS 3.3 as well as ProDOS 8. - -For ProDOS 8 system programs the load address is fixed to $2000 so there -is no need for a header. Thus the linker configuration -<htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> for those programs -omits the DOS 3.3 header. The right AppleCommander option to put system files -without a header on a ProDOS 8 disk image is <tt/-p/. - - -<sect>Memory layout<p> - -In the standard setup, cc65 generated programs use the memory from -$803 to $95FF, so 35.5 KB of RAM are available. - -Special locations: - -<descrip> - - <tag/Stack/ - The C runtime stack is located at HIMEM and grows downwards, regardless of - how your linker config file is setup. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - -While running <tt/main()/ the Language Card bank 2 is enabled for read access. -However while running module constructors/destructors the Language Card is disabled. - -Enabling the Language Card allows to use it as additional memory for cc65 -generated code. However code is never automatically placed there. Rather code -needs to be explicitly placed in the Language Card either per file by compiling -with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma -code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the -cc65 runtime system takes care of actually moving the code into the Language -Card. - -The amount of memory available in the Language Card for generated code depends -on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">. - - - -<sect>Linker configurations<p> - -The ld65 linker comes with a builtin config file for the enhanced Apple //e, -which is used via <tt/-t apple2enh/ (and displayed via <tt/--dump-config apple2enh/). -The apple2enh package comes with additional secondary linker config files, which -are used via <tt/-C <configfile>/. - - -<sect1>builtin config file<p> - -Default configuration optimized for a binary program running on ProDOS 8 with -BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card -bank 2 memory from $D400 to $DFFF. - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $803 to $95FF (35.5 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D400 to $DFFF (3 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Variable (default: $803) - - <tag><tt/HEADER:/ Binary file header</tag> - DOS 3.3 header (address and length) - -</descrip><p> - - -<sect1><tt/apple2enh-dos33.cfg/<p> - -Configuration optimized for a binary program running on DOS 3.3. A plain -vanilla DOS 3.3 doesn't make use of the Language Card at all. - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $803 to $95FF (35.5 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D000 to $FFFF (12 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Variable (default: $803) - - <tag><tt/HEADER:/ Binary file header</tag> - DOS 3.3 header (address and length) - -</descrip><p> - - -<sect1><tt/apple2enh-system.cfg/<p> - -Configuration for a system program running on ProDOS 8. - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $2000 to $BEFF (39.75 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D400 to $DFFF (3 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Fixed ($2000) - - <tag><tt/HEADER:/ Binary file header</tag> - None - -</descrip><p> - - -<sect1><tt/apple2enh-loader.cfg/<p> - -Configuration optimized for a binary program running on ProDOS 8 without -BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an -Apple ][ ProDOS 8 loader for cc65 programs/, which is available -in the cc65 User Contributions section. - -A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but -isn't tied to the start address $2000. Thus with the default start -address $800 the main memory area is increased by 6 KB. - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $800 to $BEFF (45.75 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D400 to $DFFF (3 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Variable (default: $800) - - <tag><tt/HEADER:/ Binary file header</tag> - DOS 3.3 header (address and length) - -</descrip><p> - - -<sect1><tt/apple2enh-reboot.cfg/<p> - -Configuration optimized for a binary program running on ProDOS 8 without -BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an -Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together -with the function <tt/rebootafterexit()/. - -If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather -reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of -the Language Card bank 2 at all. - -This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine! - -<descrip> - - <tag><tt/RAM:/ Main memory area</tag> - From $800 to $BEFF (45.75 KB) - - <tag><tt/LC:/ Language Card memory area</tag> - From $D000 to $DFFF (4 KB) - - <tag><tt/STARTADDRESS:/ Program start address</tag> - Variable (default: $800) - - <tag><tt/HEADER:/ Binary file header</tag> - DOS 3.3 header (address and length) - -</descrip><p> - - - -<sect>ProDOS 8 system programs<p> - -ProDOS 8 system programs are always loaded to the start address $2000. -For cc65 programs this means that the 6 KB from $800 to $2000 are -by default unused. There are however several options to make use of that memory -range. - - -<sect1>LOADER.SYSTEM<p> - -The easiest (and for really large programs in fact the only) way to have a cc65 -program use the memory from $800 to $2000 is to link it as binary -(as opposed to system) program using the linker configuration -<htmlurl url="apple2enh-4.html#ss4.4" name="apple2enh-loader.cfg"> with start address -$800 and load it with <bf/LOADER.SYSTEM - an Apple ][ -ProDOS 8 loader for cc65 programs/. The program then works like a system program -(i.e. quits to the ProDOS dispatcher). - -Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the -program to load under name <program>.SYSTEM as a system program. For -example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. - - -<sect1>Heap<p> - -If the cc65 program can be successfully linked as system program using the linker -configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but -uses the heap either explicitly or implicitly (i.e. by loading a driver) then -the memory from $800 to $2000 can be added to the heap by calling -<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/. - - -<sect1>ProDOS 8 I/O buffers<p> - -ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default -these buffers are allocated by the cc65 runtime system on the heap using -<tt/posix_memalign()/. While this is generally the best solution it means quite -some overhead for (especially rather small) cc65 programs which do open files -but don't make use of the heap otherwise. - -The apple2enh package comes with the alternative ProDOS 8 I/O buffer allocation -module <tt/apple2enh-iobuf-0800.o/ which uses the memory between $800 and -the program start address for the 1 KB I/O buffers. For system programs (with -start address $2000) this results in up to 6 I/O buffers and thus up to 6 -concurrently open files. - -While using <tt/_heapadd()/ as described in the section above together with the -default I/O buffer allocation basically yields the same placement of I/O buffers -in memory the primary benefit of <tt/apple2enh-iobuf-0800.o/ is a reduction in code -size - and thus program file size - of more than 1400 bytes. - -Using <tt/apple2enh-iobuf-0800.o/ is as simple as placing it on the linker command -line like this: - -<tscreen><verb> -cl65 -t apple2enh -C apple2enh-system.cfg myprog.c apple2enh-iobuf-0800.o -</verb></tscreen> - - - -<sect>Platform specific header files<p> - -Programs containing enhanced Apple //e specific code may use the -<tt/apple2enh.h/ header file. - - -<sect1>Enhanced Apple //e specific functions<p> - -The functions listed below are special for the enhanced Apple //e. See -the <htmlurl url="funcref.html" name="function reference"> for declaration and -usage. - -<itemize> -<item>_auxtype -<item>_dos_type -<item>_filetype -<item>get_ostype -<item>rebootafterexit -<item>ser_apple2_slot -<item>textframe -<item>textframexy -<item>tgi_apple2_mix -<item>videomode -</itemize> - - -<sect1>Hardware access<p> - -There's currently no support for direct hardware access. This does not mean -you cannot do it, it just means that there's no help. - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -<descrip> - - <tag><tt/a2e.lo.tgi (apple2_40_48_16)/</tag> - This driver features a resolution of 40×48 with 16 colors. - - The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The - function clears the corresponding area at the bottom of the screen. - - <tag><tt/a2e.hi.tgi (apple2_280_192_8)/</tag> - This driver features a resolution of 280×192 with 8 colors and two - hires pages. Note that programs using this driver will have to be linked - with <tt/--start-addr $4000/ to reserve the first hires page or with - <tt/--start-addr $6000/ to reserve both hires pages. - - Note that the second hires page is only available if the text display is not in - 80 column mode. This can be asserted by calling <tt/videomode (VIDEOMODE_40COL);/ - before installing the driver. - - The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The - function doesn't clear the corresponding area at the bottom of the screen. - - In memory constrained situations the memory from $803 to $1FFF - can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/ - at the beginning of <tt/main()/. Doing so is beneficial even if the program - doesn't use the the heap explicitly because loading the driver (and in fact - already opening the driver file) uses the heap implicitly. - -</descrip><p> - - -<sect1>Extended memory drivers<p> - -<descrip> - - <tag><tt/a2e.auxmem.emd (apple2_auxmem)/</tag> - Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended - 80-Column Text Card. - - Note that this driver doesn't check for the actual existence of the memory - and that it doesn't check for ProDOS 8 RAM disk content! - -</descrip><p> - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/a2e.stdjoy.joy (apple2_stdjoy)/</tag> - Supports up to two standard analog joysticks connected to the game port of - the enhanced Apple //e. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -<descrip> - - <tag><tt/a2e.stdmou.mou (apple2_stdmou)/</tag> - Driver for the AppleMouse II Card. Searches all Apple II slots - for an AppleMouse II Card compatible firmware. The default bounding - box is [0..279,0..191]. - - Note that the enhanced Apple //e default mouse callbacks support - text mode only. - -</descrip><p> - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/a2e.ssc.ser (apple2_ssc)/</tag> - Driver for the Apple II Super Serial Card. Supports up to 19200 baud, - hardware flow control (RTS/CTS) and interrupt driven receives. Note - that because of the peculiarities of the 6551 chip transmits are not - interrupt driven, and the transceiver blocks if the receiver asserts - flow control because of a full buffer. - - The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to - <tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/ - succeeds for all Apple II slots, but <tt/ser_open()/ fails with - <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot. - -</descrip><p> - - - -<sect>Limitations<p> - - -<sect1>DOS 3.3<p> - -Although the standard binaries generated by the linker for the enhanced Apple //e -generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with -BASIC.SYSTEM) there are some limitations for DOS 3.3: - -<descrip> - - <tag>Disk File I/O</tag> - There's no disk file I/O support. Any attempt to use it yields an error with - <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers - are in general not functional as they depend on disk file I/O. However they - may be converted to statically linked drivers using the co65 object-file - converter. - - <tag/Interrupts/ - There's no <tt/interruptor/ support. Any attempt to use it yields the message - 'Failed to alloc interrupt' on program startup. This implicitly means that - <tt/a2e.stdmou.mou/ and <tt/a2e.ssc.ser/ are not functional as they depend on - interrupts. - -</descrip><p> - - -<sect1>Direct console I/O<p> - -<descrip> - - <tag/Color/ - The enhanced Apple //e has no color text mode. Therefore the functions - <htmlurl url="funcref-205.html" name="textcolor()">, - <htmlurl url="funcref-68.html" name="bgcolor()"> and - <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. - - <tag/Cursor/ - The enhanced Apple //e has no hardware cursor. Therefore the function - <htmlurl url="funcref-88.html" name="cursor()"> has no effect. - -</descrip><p> - - - -<sect>Other hints<p> - - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not -supported by BASIC, the following syntax was chosen: - -<tscreen><verb> -]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 -</verb></tscreen> - -<enum> -<item>Arguments are separated by spaces. -<item>Arguments may be quoted. -<item>Leading and trailing spaces around an argument are ignored. Spaces within - a quoted argument are allowed. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 10 arguments (including the program name) are - supported. -</enum> - - -<sect1>Function keys<p> - -These are defined to be OpenApple + number key. - - -<sect1>Interrupts<p> - -The runtime for the enhanced Apple //e uses routines marked as -<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be -written as simple machine language subroutines and will be called -automatically by the interrupt handler code when they are linked into a -program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl -url="ca65.html" name="assembler manual">. - - -<sect1>DIO<p> - -<descrip> - - <tag/Drive ID/ - The function <htmlurl url="dio-1.html" name="dio_open()"> has the single - parameter <tt/device/ to identify the device to be opened. Therefore an - Apple II slot and drive pair is mapped to that <tt/drive_id/ according - to the formula - - <tscreen> - device = slot + (drive - 1) * 8 - </tscreen> - - so that for example slot 6 drive 2 is mapped to <tt/device/ 14. - - <tag/Sector count/ - The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns - the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8 - disk it simply always returns 280 (which is only correct for a 140 KB disk). - This condition is indicated by the <tt/_oserror/ value 82. - -</descrip><p> - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/ar65.sgml b/doc/ar65.sgml deleted file mode 100644 index d4e19a5c5..000000000 --- a/doc/ar65.sgml +++ /dev/null @@ -1,156 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>ar65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>19.07.2000 - -<abstract> -ar65 is an archiver for object files generated by ca65. It allows to create -archives, add or remove modules from archives, and to extract modules from -existing archives. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - - -ar65 is a replacement for the libr65 archiver that was part of the cc65 C -compiler suite developed by John R. Dunning. libr65 had some problems and -the copyright does not permit some things which I wanted to be possible, -so I decided to write a completely new assembler/linker/archiver suite -for the cc65 compiler. ar65 is part of this suite. - -<sect>Usage<p> - - -The archiver is called as follows: - -<tscreen><verb> - Usage: ar65 <operation> lib file|module ... - Operation is one of: - a Add modules - d Delete modules - l List library contents - x Extract modules - V Print the archiver version -</verb></tscreen> - -You may add modules to a library using the `a' command. If the library -does not exist, it is created (and a warning message is printed which you -may ignore if creation of the library was your intention). You may -specify any number of modules on the command line following the library. - -If a module with the same name exists in the library, it is replaced by -the new one. The archiver prints a warning, if the module in the library -has a newer timestamp than the one to add. - -Here's an example: - -<tscreen><verb> - ar65 a mysubs.lib sub1.o sub2.o -</verb></tscreen> - -This will add two modules to the library `mysubs.lib' creating the -library if necessary. If the library contains modules named sub1.o or -sub2.o, they are replaced by the new ones. - -Modules names in the library are stored without the path, so, using - -<tscreen><verb> - ar65 a mysubs.lib ofiles/sub1.o ofiles/sub2.o -</verb></tscreen> - -will add two modules named `sub1.o' and `sub2.o' to the library. - -Deleting modules from a library is done with the `d' command. You may not -give a path when naming the modules. - -Example: - -<tscreen><verb> - ar65 d mysubs.lib sub1.o -</verb></tscreen> - -This will delete the module named `sub1.o' from the library, printing an -error if the library does not contain that module. - - -The `l' command prints a list of all modules in the library. Any module -names on the command line are ignored. - -Example: - -<tscreen><verb> - ar65 l mysubs.lib -</verb></tscreen> - - -Using the `x' command, you may extract modules from the library. The -modules named on the command line are extracted from the library and put -into the current directory. - -Note: Because of the indexing done by the archiver, the modules may have -a changed binary layout, that is, a binary compare with the old module -(before importing it into the library) may yield differences. The -extracted modules are accepted by the linker and archiver, however, so -this is not a problem. - -Example for extracting a module from the library: - -<tscreen><verb> - ar65 x mysubs.lib sub1.o -</verb></tscreen> - - -The `V' command prints the version number of the assembler. If you send -any suggestions or bugfixes, please include your version number. - -In addition to these operations, the archiver will check for, and warn -about duplicate external symbols in the library, every time when an -operation does update the library. This is only a warning, the linker -will ignore one of the duplicate symbols (which one is unspecified). - - -<sect>Bugs/Feedback<p> - -If you have problems using the archiver, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). - - - -<sect>Copyright<p> - -ar65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von -Bassewitz. For usage of the binaries and/or sources the following conditions -do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> - - - diff --git a/doc/atari.sgml b/doc/atari.sgml deleted file mode 100644 index 9fe75ec2a..000000000 --- a/doc/atari.sgml +++ /dev/null @@ -1,590 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Atari specific information for cc65 -<author>Shawn Jefferson, <htmlurl -url="mailto:shawnjefferson@24fightingchickens.com" -name="shawnjefferson@24fightingchickens.com"> and -Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org"> -<date>03-Jan-2006 - -<abstract> -An overview over the Atari runtime system as it is implemented for the cc65 C -compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the Atari runtime system as it comes -with the cc65 C compiler. It describes the memory layout, Atari specific -header files, available drivers, and any pitfalls specific to that -platform. - -Please note that Atari specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the -Atari target is a machine language program with a standard executable -header (FF FF <2 byte start address> <2 bytes end address> -[program bytes]). These values are calculated in the crt0.s -file from the __STARTUP_LOAD__ and __ZPSAVE_LOAD__ values, so keep -this in mind if you create a custom linker config file and start -moving segments around (see section -<ref name="Reserving a memory area inside the program" id="memhole">). -You can override this behaviour by creating your own crt0.s file and -linking it into your program. A run vector is added to the end of the -file ($02E0 <run vector>) and is calculated using -__STARTUP_LOAD__ in crt0.s. - - -<sect>Memory layout<p> - -The default linker script assumes that the BASIC ROM is disabled (or -the BASIC cartridge unplugged). This gives a usable memory range from -$2E00 - $BC1F. The library startup code examines the -current memory configuration, which depends on the size of the -installed memory and cartridges present, by inspecting the value in -the MEMTOP ($2E5) variable. Then the initial stack pointer, -which indicates the upper bound of memory used, is adjusted. The -default load address of $2E00 was chosen to accommodate having -a DOS loaded and a driver that resides in low memory such as the 850 -R: handler. You can override this behaviour by creating a custom -linker config file or by using the "--start-addr" cl65 command line -argument or the "--start-addr" or "-S" ld65 command line arguments. - -Special locations: - -<descrip> - <tag/Text screen/ - The text screen depends on the installed memory size and cartridges - and can be obtained from the SAVMSC variable ($58). - - <tag/Stack/ - The C runtime stack is located at MEMTOP and grows downwards, - regardless of how your linker config file is setup. This - accommodates the different memory configurations of the Atari - machines, as well as having a cartridge installed. You can override - this behaviour by writing your own crt0.s file and linking it to - your program (see also <ref name="Final note" - id="memhole_final_note">). - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing Atari specific code may use the <tt/atari.h/ -header file. - - -<sect1>Atari specific functions<p> - -The functions and global variable listed below are special for the Atari. -See the <htmlurl url="funcref.html" name="function reference"> for declaration and usage. - -<itemize> -<item>get_ostype -<item>get_tv -<item>_dos_type -<item>_gtia_mkcolor -<item>_getcolor -<item>_getdefdev -<item>_graphics -<item>_rest_vecs -<item>_save_vecs -<item>_scroll -<item>_setcolor -<item>_setcolor_low -</itemize> - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/atari.h/ header -file do allow access to hardware located in the address space. Some -variables are structures, accessing the struct fields will access the -chip registers. - -<descrip> - - <tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag> - The <tt/GTIA_READ/ structure allows read access to the GTIA. The - <tt/GTIA_WRITE/ structure allows write access to the GTIA. - See the <tt/_gtia.h/ header file located in the include directory - for the declaration of the structure. - - <tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag> - The <tt/POKEY_READ/ structure allows read access to the POKEY. The - <tt/POKEY_WRITE/ structure allows write access to the POKEY. - See the <tt/_pokey.h/ header file located in the include directory - for the declaration of the structure. - - <tag><tt/ANTIC/</tag> - The <tt/ANTIC/ structure allows read access to the ANTIC. - See the <tt/_antic.h/ header file located in the include directory - for the declaration of the structure. - - <tag><tt/PIA/</tag> - The <tt/PIA/ structure allows read access to the PIA 6520. - See the <tt/_pia.h/ header file located in the include directory - for the declaration of the structure. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -<descrip> - - <tag><tt/atari10.tgi (atari_10)/</tag> - - <tag><tt/atr10p2.tgi (atari_10p2)/</tag> - - <tag><tt/atari11.tgi (atari_11)/</tag> - - <tag><tt/atari14.tgi (atari_14)/</tag> - - <tag><tt/atari15.tgi (atari_15)/</tag> - - <tag><tt/atr15p2.tgi (atari_15p2)/</tag> - - <tag><tt/atari3.tgi (atari_3)/</tag> - - <tag><tt/atari4.tgi (atari_4)/</tag> - - <tag><tt/atari5.tgi (atari_5)/</tag> - - <tag><tt/atari6.tgi (atari_6)/</tag> - - <tag><tt/atari7.tgi (atari_7)/</tag> - - <tag><tt/atari8.tgi (atari_8)/</tag> - - <tag><tt/atr8p2.tgi (atari_8p2)/</tag> - - <tag><tt/atari9.tgi (atari_9)/</tag> - - <tag><tt/atr9p2.tgi (atari_9p2)/</tag> - -</descrip><p> - -Many graphics modes require more memory than the text screen which is -in effect when the program starts up. Therefore the programmer has to -tell the program beforehand the memory requirements of the graphics -modes the program intends to use. -This can be done by using the __RESERVED_MEMORY__ linker config -variable. The number specified there describes the number of bytes to -subtract from the top of available memory as seen from the runtime -library. This memory is then used by the screen buffer. - -The numbers for the different graphics modes presented below should -only be seen as a rule of thumb. Since the screen buffer memory needs -to start at specific boundaries, the numbers depend on the current top -of available memory. -The following numbers were determined by a BASIC program. - -<table> -<tabular ca="rr"> -graphics mode|reserved memory@<hline> -0|1@ -1|1@ -2|1@ -3|1@ -4|1@ -5|182@ -6|1182@ -7|3198@ -8|7120@ -9|7146@ -10|7146@ -11|7146@ -12|162@ -13|1@ -14|3278@ -15|7120@ -16|1@ -17|1@ -18|1@ -19|1@ -20|1@ -21|184@ -22|1192@ -23|3208@ -24|7146@ -25|7146@ -26|7146@ -27|7146@ -28|162@ -29|1@ -30|3304@ -31|7146 -</tabular> -<caption>reserved memory required for different graphics modes -</table> - -The values of "1" are needed because the graphics command crashes if -it doesn't have at least one byte available. This seems to be a bug of -the Atari ROM code. - -<sect1>Extended memory drivers<p> - -<descrip> - - <tag><tt/atr130xe.emd (atari_130xe)/</tag> - -</descrip><p> - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/ataristd.joy (atari_stdjoy)/</tag> - Supports up to four standard joysticks connected to the joystick ports of - the Atari. - - <tag><tt/atarim8.joy (atari_multijoy)/</tag> - Supports up to eight standard joysticks connected to a MultiJoy adapter. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -Currently no drivers available (in fact, the API for loadable mouse drivers -does not exist). There is a static driver you can use. - - -<sect1>RS232 device drivers<p> - -Currently there are no RS232 loadable drivers available for the Atari -platform. There is a static driver you can use. - - -<sect>Limitations<p> - - -<sect>DIO implementation<label id="dio"><p> - -The Atari supports disk drives with either 128 or 256 byte sectors. -The first three sectors of any disk are always 128 bytes long though. This is -because the system can only boot from 128 bytes sectors. - -Therefore the DIO read and write functions transfer only 128 bytes -for sectors 1 to 3, regardless of the type of diskette. - - -<sect>CONIO implementation<label id="conio"><p> - -The console I/O is speed optimized therefore support for XEP80 hardware -or f80.com software is missing. Of course you may use stdio.h functions. - - -<sect>Other hints<p> - - -<sect1>Function keys<p> - -Function keys are mapped to Atari + number key. - - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/ when DOS supports it. - -<enum> -<item>Arguments are separated by spaces. -<item>Leading and trailing spaces around an argument are ignored. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 16 arguments (including the program name) are - supported. -</enum> - - -<sect1>Interrupts<p> - -The runtime for the Atari uses routines marked as <tt/.INTERRUPTOR/ for -interrupt handlers. Such routines must be written as simple machine language -subroutines and will be called automatically by the VBI handler code -when they are linked into a program. See the discussion of the <tt/.CONDES/ -feature in the <htmlurl url="ca65.html" name="assembler manual">. - - -<sect1>Reserving a memory area inside a program<label id="memhole"><p> - -The Atari 130XE maps its additional memory into CPU memory in 16K -chunks at address $4000 to $7FFF. One might want to -prevent this memory area from being used by cc65. Other reasons to -prevent the use of some memory area could be to reserve space for the -buffers for display lists and screen memory. -<p> -The Atari executable format allows holes inside a program, e.g. one -part loads into $2E00 to $3FFF, going below the reserved -memory area (assuming a reserved area from $4000 to -$7FFF), and another part loads into $8000 to -$BC1F. -<p> -Each load chunk of the executable starts with a 4 byte header which -defines its load address and size. In the following linker scripts -these headers are named HEADER and SECHDR (for the MEMORY layout), and -accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout). -<p> -<sect2>Low code and high data example<p> -Goal: Create an executable with 2 load chunks which doesn't use the -memory area from $4000 to $7FFF. The CODE segment of -the program should go below $4000 and the DATA and RODATA -segments should go above $7FFF. -<p> -The main problem is that the EXE header generated by the cc65 runtime -lib is wrong. It defines a single load chunk with the sizes/addresses -of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments (the whole user -program). -<p> -The contents of the EXE header come from the EXEHDR segment, which is -defined in crt0.s. This cannot be changed without modifying and -recompiling the cc65 atari runtime lib. Therefore the original EXE -header must be discarded. It will be replaced by a user created -one. The discarding is done by assigning the EXEHDR segment to the -BANK memory area. The BANK memory area is discarded in the new linker -script (written to file ""). -<p> -The user needs to create a customized linker config file which adds -new memory areas and segments to hold the new EXE header and the -header data for the second load chunk. Also an assembly source file -needs to be created which defines the contents of the new EXE header -and the second load chunk header. -<p> -<p> -This is an example of a modified cc65 Atari linker configuration file -(split.cfg): -<tscreen><verb> -SYMBOLS { - __STACKSIZE__ = $800; # 2K stack - __RESERVED_MEMORY__: value = $0000, weak = yes; -} -FEATURES { - STARTADDRESS: default = $2E00; -} -MEMORY { - ZP: start = $82, size = $7E, type = rw, define = yes; - - HEADER: start = $0000, size = $6, file = %O; # first load chunk - RAMLO: start = %S, size = $4000 - %S, file = %O; - - BANK: start = $4000, size = $4000, file = ""; - - SECHDR: start = $0000, size = $4, file = %O; # second load chunk - RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F -} -SEGMENTS { - EXEHDR: load = BANK, type = ro; - - NEXEHDR: load = HEADER, type = ro; # first load chunk - STARTUP: load = RAMLO, type = ro, define = yes; - LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes; - INIT: load = RAMLO, type = ro, optional = yes; - CODE: load = RAMLO, type = ro, define = yes; - - CHKHDR: load = SECHDR, type = ro; # second load chunk - RODATA: load = RAM, type = ro, define = yes; - DATA: load = RAM, type = rw, define = yes; - BSS: load = RAM, type = bss, define = yes; - ZPSAVE: load = RAM, type = bss, define = yes; - - ZEROPAGE: load = ZP, type = zp; - AUTOSTRT: load = RAM, type = ro; # defines program entry point -} -FEATURES { - CONDES: segment = RODATA, - type = constructor, - label = __CONSTRUCTOR_TABLE__, - count = __CONSTRUCTOR_COUNT__; - CONDES: segment = RODATA, - type = destructor, - label = __DESTRUCTOR_TABLE__, - count = __DESTRUCTOR_COUNT__; -} -</verb></tscreen> -<p> - -A new memory area BANK was added which describes the reserved area. -It gets loaded with the contents of the old EXEHDR segment. But the -memory area isn't written to the output file. This way the contents of -the EXEHDR segment get discarded. -<p> -The newly added NEXEHDR segment defines the correct EXE header. It -puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the -segments containing only code, into load chunk #1 (RAMLO memory area). -<p> -The header for the second load chunk comes from the new CHKHDR -segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load -chunk #2 (RAM memory area). -<p> -<p> -The contents of the new NEXEHDR and CHKHDR segments come from this -file (split.s): -<tscreen><verb> - .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__ - .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__ - - .segment "NEXEHDR" - .word $FFFF - .word __STARTUP_LOAD__ - .word __CODE_LOAD__ + __CODE_SIZE__ - 1 - - .segment "CHKHDR" - .word __RODATA_LOAD__ - .word __BSS_LOAD__ - 1 -</verb></tscreen> -<p> -Compile with -<tscreen><verb> -cl65 -t atari -C split.cfg -o prog.com prog.c split.s -</verb></tscreen> - -<sect2>Low data and high code example<p> - - -Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT, -CODE, BSS, ZPSAVE into high memory (split2.cfg): - -<tscreen><verb> -SYMBOLS { - __STACKSIZE__ = $800; # 2K stack - __RESERVED_MEMORY__: value = $0000, weak = yes; -} -FEATURES { - STARTADDRESS: default = $2E00; -} -MEMORY { - ZP: start = $82, size = $7E, type = rw, define = yes; - - HEADER: start = $0000, size = $6, file = %O; # first load chunk - RAMLO: start = %S, size = $4000 - %S, file = %O; - - BANK: start = $4000, size = $4000, file = ""; - - SECHDR: start = $0000, size = $4, file = %O; # second load chunk - RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F -} -SEGMENTS { - EXEHDR: load = BANK, type = ro; # discarded old EXE header - - NEXEHDR: load = HEADER, type = ro; # first load chunk - RODATA: load = RAMLO, type = ro, define = yes; - DATA: load = RAMLO, type = rw, define = yes; - - CHKHDR: load = SECHDR, type = ro; # second load chunk - STARTUP: load = RAM, type = ro, define = yes; - INIT: load = RAM, type = ro, optional = yes; - CODE: load = RAM, type = ro, define = yes; - ZPSAVE: load = RAM, type = bss, define = yes; - BSS: load = RAM, type = bss, define = yes; - - ZEROPAGE: load = ZP, type = zp; - AUTOSTRT: load = RAM, type = ro; # defines program entry point -} -FEATURES { - CONDES: segment = RODATA, - type = constructor, - label = __CONSTRUCTOR_TABLE__, - count = __CONSTRUCTOR_COUNT__; - CONDES: segment = RODATA, - type = destructor, - label = __DESTRUCTOR_TABLE__, - count = __DESTRUCTOR_COUNT__; -} -</verb></tscreen> - -New contents for NEXEHDR and CHKHDR are needed (split2.s): -<tscreen><verb> - .import __STARTUP_LOAD__, __ZPSAVE_LOAD__, __DATA_SIZE__ - .import __DATA_LOAD__, __RODATA_LOAD__ - - .segment "NEXEHDR" - .word $FFFF - .word __RODATA_LOAD__ - .word __DATA_LOAD__ + __DATA_SIZE__ - 1 - - .segment "CHKHDR" - .word __STARTUP_LOAD__ - .word __ZPSAVE_LOAD__ - 1 -</verb></tscreen> - -Compile with -<tscreen><verb> -cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s -</verb></tscreen> - -<sect2>Final note<label id="memhole_final_note"><p> - -There are two other memory areas which don't appear directly in the -linker script. They are the stack and the heap. - -The cc65 runtime lib places the stack location at the end of available -memory. This is dynamically set from the MEMTOP system variable at -startup. The heap is located in the area between the end of the BSS -segment and the top of the stack as defined by __STACKSIZE__. - -If BSS and/or the stack shouldn't stay at the end of the program, -some parts of the cc65 runtime lib need to be replaced/modified. - -common/_heap.s defines the location of the heap and atari/crt0.s -defines the location of the stack by initializing sp. - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org"> or <htmlurl url="mailto:chris@groessler.org" -name="chris@groessler.org"> ). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/atmos.sgml b/doc/atmos.sgml deleted file mode 100644 index 8e24c92a1..000000000 --- a/doc/atmos.sgml +++ /dev/null @@ -1,260 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Oric Atmos specific information for cc65 -<author>Ullrich von Bassewitz <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"><newline> -Stefan A. Haubenthal <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"><newline> -<url url="mailto:greg.king5@verizon.net" name="Greg King"> -<date>2013-01-08 - -<abstract> -An overview over the Atmos runtime system as it is implemented for the cc65 C -compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the Atmos runtime system as it comes with the -cc65 C compiler. It describes the memory layout, Atmos specific header files, -available drivers, and any pitfalls specific to that platform. - -Please note that Atmos specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the Atmos target -is a machine language program with a 17 byte tape header including a cc65 tag. -The standard load and autostart address is $500. - - -<sect>Memory layout<p> - -In the standard setup, cc65 generated programs use the memory from -$500 to $9800, so nearly 37K of memory (including the stack) is -available. ROM calls are possible without further precautions. - -Special locations: - -<descrip> - <tag/Stack/ - The C runtime stack is located at $97FF and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing Atmos specific code may use the <tt/atmos.h/ header file. - - -<sect1>Atmos specific functions<p> - -The functions listed below are special for the Atmos. See the <htmlurl -url="funcref.html" name="function reference"> for declaration and usage. - -<itemize> -<item>atmos_load -<item>atmos_save -</itemize> - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/atmos.h/ header file do allow -access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<descrip> - - <tag><tt/VIA/</tag> - Access to the VIA (versatile interface adapter) chip is available via the - <tt/VIA/ variable. The structure behind this variable is explained in <tt/_6522.h/. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -<em>Note:</em> Since the Atmos doesn't have working disk I/O -(see <ref id="limitations" name="section "Limitations"">), the -available drivers cannot be loaded at runtime (so the term "loadable drivers" -is somewhat misleading). Instead, the drivers have to be statically linked. While -this may seem overhead, it has two advantages: - -<enum> -<item>The interface is identical to the one used for other platforms - and to the one for the Atmos once it has disk I/O. -<item>Once disk I/O is available, existing code can be changed to load drivers - at runtime with almost no effort. -</enum> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -<descrip> - - <tag><tt/atmos-228-200-3.tgi (atmos_228_200_3)/</tag> - This driver was written by Greg King and Stefan Haubenthal. - It features a resolution of 228×200 with a palette of two colors that - can be chosen from the Atmos's eight colors. The driver supports a third - palette-"color" that actually "flips" the pixel (it becomes the other color) - that is on the screen under the graphics cursor. - - <tag><tt/atmos-240-200-2.tgi (atmos_240_200_2)/</tag> - This driver was written by Stefan Haubenthal and Greg King. - It features a resolution of 240×200 with black and white colors. - It is the default graphics driver for the Atmos. - -</descrip><p> - - -<sect1>Extended memory drivers<p> - -No extended memory drivers are currently available for the Atmos. - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/atmos-pase.joy (atmos_pase)/</tag> - Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -No mouse drivers are currently available for the Atmos. - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/atmos-acia.ser (atmos_acia)/</tag> - Driver for the Telestrat integrated serial controller and the Atmos with a - serial add-on. - Note that because of the peculiarities of the 6551 chip together with the - use of the NMI, transmits are not interrupt driven, and the transceiver - blocks if the receiver asserts flow control because of a full buffer. - -</descrip><p> - - - -<sect>Limitations<label id="limitations"><p> - -<sect1>Disk I/O<p> - -The existing library for the Atmos doesn't implement C file -I/O. There is one hack for the <tt/write()/ routine in -place, which will make functions work that write to <tt/stdout/ -(like <tt/printf()/). However, this function has some shortcomings which -won't be fixed, because it's going to be replaced anyway. - -To be more concrete, this limitation means that you cannot use any of the -following functions (and a few others): - -<itemize> -<item>fclose -<item>fopen -<item>fread -<item>fprintf -<item>fputc -<item>fscanf -<item>fwrite -<item>... -</itemize> - - - -<sect>Other hints<p> - -<sect1>Function keys<p> - -These are defined to be FUNCT + number key. - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/. Since this is not -supported by BASIC, the following syntax was chosen: - -<tscreen><verb> - CALL#500:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 -</verb></tscreen> - -<enum> -<item>Arguments are separated by spaces. -<item>Arguments may be quoted. -<item>Leading and trailing spaces around an argument are ignored. Spaces within - a quoted argument are allowed. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 10 arguments (including the program name) are - supported. -</enum> - - -<sect1>Interrupts<p> - -The runtime for the Atmos uses routines marked as <tt/.INTERRUPTOR/ for -interrupt handlers. Such routines must be written as simple machine language -subroutines and will be called automatically by the interrupt handler code -when they are linked into a program. See the discussion of the <tt/.CONDES/ -feature in the <htmlurl url="ca65.html" name="assembler manual">. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> - - - diff --git a/doc/c128.sgml b/doc/c128.sgml deleted file mode 100644 index 37cdd25f8..000000000 --- a/doc/c128.sgml +++ /dev/null @@ -1,356 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Commodore 128 specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-12-14 - -<abstract> -An overview over the C128 runtime system as it is implemented for the cc65 C -compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the C128 runtime system as it comes with the -cc65 C compiler. It describes the memory layout, C128 specific header files, -available drivers, and any pitfalls specific to that platform. - -Please note that C128 specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the C128 target -is a machine language program with a one line BASIC stub, which calls the -machine language part via SYS. This means that a program can be loaded as -BASIC program and started with RUN. It is of course possible to change this -behaviour by using a modified startup file and linker config. - - -<sect>Memory layout<p> - -cc65 generated programs with the default setup run with the I/O area and the -kernal ROM enabled. Note that this is a non standard memory layout, and that -there is no "memory configuration index" for this layout. This means that -special care has to be taken when changing the configuration, or calling any -code that does this. The memory configuration register at $FF00 should -be saved and restored instead of relying on the memory configuration index -stored in the zero page. - -The setup gives a usable memory range of $1C00 - $BFFF. Having -just the kernal ROM mapped in means, that kernal entry points may be called -directly, but using the BASIC ROM is not possible without additional code. - -Special locations: - -<descrip> - <tag/Text screen/ - The text screen is located at $400 (as in the standard setup). - - <tag/Stack/ - The C runtime stack is located at $BFFF and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing C128 specific code may use the <tt/c128.h/ or <tt/cbm.h/ -header files. Using the later may be an option when writing code for more than -one CBM platform, since it includes <tt/c128.h/ and declares several functions -common to all CBM platforms. - - -<sect1>C128 specific functions<p> - -The functions listed below are special for the C128. See the <htmlurl -url="funcref.html" name="function reference"> for declaration and usage. - -<itemize> -<item>videomode -<item>c64mode -<item>fast -<item>slow -</itemize> - - -<sect1>CBM specific functions<p> - -Some functions are available for all (or at least most) of the Commodore -machines. See the <htmlurl url="funcref.html" name="function reference"> for -declaration and usage. - -<itemize> -<item>cbm_close -<item>cbm_closedir -<item>cbm_k_setlfs -<item>cbm_k_setnam -<item>cbm_k_load -<item>cbm_k_save -<item>cbm_k_open -<item>cbm_k_close -<item>cbm_k_readst -<item>cbm_k_chkin -<item>cbm_k_ckout -<item>cbm_k_basin -<item>cbm_k_bsout -<item>cbm_k_clrch -<item>cbm_load -<item>cbm_open -<item>cbm_opendir -<item>cbm_read -<item>cbm_readdir -<item>cbm_save -<item>cbm_write -<item>get_tv -</itemize> - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/c128.h/ header file do -allow access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<descrip> - - <tag><tt/VIC/</tag> - The <tt/VIC/ structure allows access to the VIC II (the graphics - controller). See the <tt/_vic2.h/ header file located in the include - directory for the declaration of the structure. - - <tag><tt/SID/</tag> - The <tt/SID/ structure allows access to the SID (the sound interface - device). See the <tt/_sid.h/ header file located in the include directory - for the declaration of the structure. - - <tag><tt/VDC/</tag> - The <tt/VDC/ structure allows access to the VDC (the video display - controller). See the <tt/_vdc.h/ header file located in the include - directory for the declaration of the structure. - - <tag><tt/CIA1, CIA2/</tag> - Access to the two CIA (complex interface adapter) chips is available via - the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables - is explained in <tt/_6526.h/. - - <tag><tt/COLOR_RAM/</tag> - A character array that mirrors the color RAM of the C128 at $D800. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -Note: The graphics drivers for the VDC are incompatible with the extended -memory drivers using the VDC memory! - -<descrip> - <tag><tt/c128-vdc.tgi (c128_640_200_2)/</tag> - This driver was written by Maciej Witkowiak. It uses the 80 column display - and features a resolution of 640*200 with two colors and an adjustable - palette (that means that the two colors can be chosen out of the 16 VDC - colors). - - <tag><tt/c128-vdc2.tgi (c128_640_480_2)/</tag> - This driver was written by Maciej Witkowiak. This driver uses the 80 column - display and features a resolution of 640*480 with two colors and an - adjustable palette (that means that the two colors can be chosen out of the - 16 VDC colors). The driver requires 64KB VDC RAM. -</descrip><p> - -Note: The colors are translated from definitions in headers to correct VDC values -so please use definitions or VIC color numbers only. Colors <tt/GRAY3/ and <tt/BROWN/ are -missing on VDC and are translated to the two colors missing from VIC palette. - -<sect1>Extended memory drivers<p> - -<descrip> - - <tag><tt/c128-georam.emd (c128_georam)/</tag> - A driver for the GeoRam cartridge. The driver will always assume 2048 pages - of 256 bytes each. There are no checks, so if your program knows better, - just go ahead. - - <tag><tt/c128-ram.emd (c128_ram)/</tag> - An extended memory driver for the RAM in page 1. The common memory area is - excluded, so this driver supports 251 pages of 256 bytes each. - - <tag><tt/c128-ram2.emd (c128_ram2)/</tag> - - An extended memory driver for the RAM in pages 1-3. The common memory area - is excluded, so this driver supports up to 731 pages of 256 bytes each. The - driver can be used as a full replacement for <tt/c128-ram.emd/, because RAM - in pages 2+3 is autodetected, but it's larger and there are not many - machines with RAM in banks 2+3, so it has been made a separate driver. The - additional code was contributed by Marco van den Heuvel. - - <tag><tt/c128-ramcart.emd (c128_ramcart)/</tag> - A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. - Will test the hardware for the available RAM. - - <tag><tt/c128-reu.emd (c128_reu)/</tag> - A driver for the CBM REUs. The driver will determine from the connected REU - if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, - but since there are no range checks, the application can use more memory if - it has better knowledge about the hardware than the driver. - - <tag><tt/c128-vdc.emd (c128_vdc)/</tag> - A driver for the VDC memory of the C128 written and contributed by Maciej - Witkowiak. Autodetects the amount of memory available (16 or 64K) and offers - 64 or 256 pages of 256 bytes each. Note: This driver is incompatible with - any of the graphics drivers using the VDC! - -</descrip><p> - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/c128-ptvjoy.joy (c128_ptvjoy)/</tag> - Driver for the Protovision 4-player adapter originally written by Groepaz - for the C64 and converted for the C128 by me. See <htmlurl - url="http://www.protovision-online.de/hardw/hardwstart.htm" - name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and - building instructions. Up to four joysticks are supported. - - <tag><tt/c128-stdjoy.joy (c128_stdjoy)/</tag> - Supports up to two joysticks connected to the standard joysticks port of - the C128. - -</descrip><p> - - - -<sect1>Mouse drivers<p> - -<descrip> - - <tag><tt/c128-1351.mou (c128_1351)/</tag> - Supports a standard mouse connected to port #0 of the C128. - - <tag><tt/c128-joy.mou (c128_joymouse)/</tag> - Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port - #1 of the C128. - - <tag><tt/c128-pot.mou (c128_potmouse)/</tag> - Supports a potentiometer device e.g. Koala Pad connected to port #1 of - the C128. - -</descrip><p> - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/c128-swlink.ser (c128_swlink)/</tag> - Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow - control (RTS/CTS) and interrupt driven receives. Note that because of the - peculiarities of the 6551 chip together with the use of the NMI, transmits - are not interrupt driven, and the transceiver blocks if the receiver asserts - flow control because of a full buffer. - - The driver uses the RS232 variables and buffers of the kernal (buffers at - $C00 and $D00). - -</descrip><p> - - - -<sect>Limitations<p> - - - -<sect>Other hints<p> - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/. Since this is not -supported by BASIC, the following syntax was chosen: - -<tscreen><verb> - RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 -</verb></tscreen> - -<enum> -<item>Arguments are separated by spaces. -<item>Arguments may be quoted. -<item>Leading and trailing spaces around an argument are ignored. Spaces within - a quoted argument are allowed. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 10 arguments (including the program name) are - supported. -</enum> - - -<sect1>Program return code<p> - -The program return code (low byte) is passed back to BASIC by use of the -<tt/ST/ variable. - - -<sect1>Interrupts<p> - -The runtime for the C128 uses routines marked as <tt/.INTERRUPTOR/ for -interrupt handlers. Such routines must be written as simple machine language -subroutines and will be called automatically by the interrupt handler code -when they are linked into a program. See the discussion of the <tt/.CONDES/ -feature in the <htmlurl url="ca65.html" name="assembler manual">. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/c16.sgml b/doc/c16.sgml deleted file mode 100644 index 110082a19..000000000 --- a/doc/c16.sgml +++ /dev/null @@ -1,274 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Commodore 16/116 specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-12-15 - -<abstract> -An overview over the C16 runtime system as it is implemented for the cc65 C -compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the C16 runtime system as it comes with the -cc65 C compiler. It describes the memory layout, C16/116 specific header -files, available drivers, and any pitfalls specific to that platform. - -Please note that C16 specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - -Since the C16/C116 and the Commodore Plus/4 are almost identical (the former -don't have the 6551 ACIA and only 16KB of memory), the <htmlurl -url="plus4.html" name="Plus/4 documentation"> is also worth a look. The -difference between both cc65 targets is that the Plus/4 runtime uses banking -to support full 64K RAM, while the C16 does not use banking and supports up to -32K RAM. Because banking is not needed, most C16 programs will be somewhat -smaller than the same program compiled for the Plus/4. However, programs C16 -will always run on the Plus/4, while the reverse is not necessarily true. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the C16/116 -target is a machine language program with a one line BASIC stub which, calls -the machine language part via SYS. This means that a program can be loaded as -BASIC program and started with RUN. It is of course possible to change this -behaviour by using a modified startup file and linker config. - - -<sect>Memory layout<p> - -cc65 generated programs with the default setup run with the kernal and basic -banked in. This gives a usable memory range of $1000 - $4000 -(or $8000 if the machine is equipped with 32K RAM or more). Having the -kernal and basic ROMs banked in means, that ROM entry points may be called -directly from user code. - -Special locations: - -<descrip> - <tag/Text screen/ - The text screen is located at $C00 (as in the standard setup). - - <tag/Color RAM/ - The color RAM is located at $800 (standard location). - - <tag/Stack/ - The C runtime stack is located at $3FFF ($7FFF in case of a - machine with 32K of memory or more) and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing C16 specific code may use the <tt/c16.h/ or <tt/cbm.h/ -header files. Using the later may be an option when writing code for more than -one CBM platform, since it includes <tt/c16.h/ and declares several functions -common to all CBM platforms. - -Please note that most of the header file declarations from the <tt/c16.h/ -header file are shared between the C16 and Plus/4 configurations. For this -reason, most of it is located in a common header file named <tt/cbm264.h/. - - - -<sect1>C16/C116 specific functions<p> - -There are currently no special C16/C116 functions. - - -<sect1>CBM specific functions<p> - -Some functions are available for all (or at least most) of the Commodore -machines. See the <htmlurl url="funcref.html" name="function reference"> for -declaration and usage. - -<itemize> -<item>cbm_close -<item>cbm_closedir -<item>cbm_k_setlfs -<item>cbm_k_setnam -<item>cbm_k_load -<item>cbm_k_save -<item>cbm_k_open -<item>cbm_k_close -<item>cbm_k_readst -<item>cbm_k_chkin -<item>cbm_k_ckout -<item>cbm_k_basin -<item>cbm_k_bsout -<item>cbm_k_clrch -<item>cbm_load -<item>cbm_open -<item>cbm_opendir -<item>cbm_read -<item>cbm_readdir -<item>cbm_save -<item>cbm_write -<item>get_tv -</itemize> - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/c16.h/ header file do -allow access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<descrip> - - <tag><tt/TED/</tag> - The <tt/TED/ structure allows access to the TED chip. See the - <tt/_ted.h/ header file located in the include directory for the - declaration of the structure. - - <tag><tt/COLOR_RAM/</tag> - A character array that mirrors the color RAM of the C16 at $0800. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -No graphics drivers are currently available for the C16/C116. - - -<sect1>Extended memory drivers<p> - -<descrip> - - <tag><tt/c16-ram.emd (c16_ram)/</tag> - A driver for the hidden RAM below the BASIC and KERNAL ROMs. Supports 125 - pages with 256 bytes each if the machine is equipped with 64K of memory - (a Plus/4 or a memory extended C16/116). - -</descrip><p> - - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/c16-stdjoy.joy (c16_stdjoy)/</tag> - Supports up to two joysticks connected to the standard joysticks port of - the Commodore 16/116. - -</descrip><p> - - - -<sect1>Mouse drivers<p> - -Currently no drivers available (in fact, the API for loadable mouse drivers -does not exist). - - -<sect1>RS232 device drivers<p> - -The Commodore 16 does not have a builtin ACIA and no RS232 extensions are -known. For this reason, there are no RS232 drivers available. Please note that -the standard Plus/4 driver will <em>not</em> run together with the C16 -library, because the latter does not support interrupts needed by the driver. - - -<sect>Limitations<p> - - - -<sect>Other hints<p> - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/. Since this is not -supported by BASIC, the following syntax was chosen: - -<tscreen><verb> - RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 -</verb></tscreen> - -<enum> -<item>Arguments are separated by spaces. -<item>Arguments may be quoted. -<item>Leading and trailing spaces around an argument are ignored. Spaces within - a quoted argument are allowed. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 10 arguments (including the program name) are - supported. -</enum> - - -<sect1>Program return code<p> - -The program return code (low byte) is passed back to BASIC by use of the -<tt/ST/ variable. - - -<sect1>Interrupts<p> - -The runtime for the C16 uses routines marked as <tt/.INTERRUPTOR/ for -interrupt handlers. Such routines must be written as simple machine language -subroutines and will be called automatically by the interrupt handler code -when they are linked into a program. See the discussion of the <tt/.CONDES/ -feature in the <htmlurl url="ca65.html" name="assembler manual">. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> - - - - diff --git a/doc/c64.sgml b/doc/c64.sgml deleted file mode 100644 index 2e6a37e77..000000000 --- a/doc/c64.sgml +++ /dev/null @@ -1,405 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Commodore 64 specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-09-23 - -<abstract> -An overview over the C64 runtime system as it is implemented for the cc65 C -compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the C64 runtime system as it comes with the -cc65 C compiler. It describes the memory layout, C64 specific header files, -available drivers, and any pitfalls specific to that platform. - -Please note that C64 specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the C64 target -is a machine language program with a one line BASIC stub, which calls the -machine language part via SYS. This means that a program can be loaded as -BASIC program and started with RUN. It is of course possible to change this -behaviour by using a modified startup file and linker config. - - -<sect>Memory layout<p> - -cc65 generated programs with the default setup run with the I/O area and the -kernal ROM enabled (memory under the kernal may be used for graphics or as -extended memory - see the sections about graphics and extended memory -drivers). The BASIC ROM is disabled, which gives a usable memory range of -$0800 - $CFFF. This means that kernal entry points may be called -directly, but using the BASIC ROM is not possible without additional code. - -Special locations: - -<descrip> - <tag/Text screen/ - The text screen is located at $400 (as in the standard setup). - - <tag/Stack/ - The C runtime stack is located at $CFFF and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - -<sect>Linker configurations<p> - -The ld65 linker comes with a builtin config file for the Commodore 64, -which is used via <tt/-t c64/ (and displayed via <tt/--dump-config c64/). The -c64 package comes with additional secondary linker config files, which are -used via <tt/-C <configfile>/. - - -<sect1>builtin config file<p> - -The builtin configuration is tailored to C programs. It supplies the load -address and a small BASIC stub that starts the compiled program using a SYS -command. - - -<sect1><tt/c64-asm.cfg/<p> - -This configuration is made for assembler programmers who don't need a special -setup. The default start address is $801. It can be changed with the -linker command line option <tt/--start-addr/. All standard segments with the -exception of <tt/zeropage/ are written to the output file and a two byte load -address is prepended. - -To use this config file, assemble with <tt/-t c64/ and link with <tt/-C -c64-asm.cfg/. The former will make sure that correct character translation is -in effect, while the latter supplies the actual config. When using <tt/cl65/, -use both command line options. - -Sample command line for <tt/cl65/: - -<tscreen><verb> -cl65 -o file.prg -t c64 -C c64-asm.cfg source.s -</verb></tscreen> - -To generate code that loads to $C000: - -<tscreen><verb> -cl65 -o file.prg --start-addr $C000 -t c64 -C c64-asm.cfg source.s -</verb></tscreen> - -It is also possible to add a small BASIC header to the program, that uses SYS -to jump to the program entry point (which is the start of the code segment). -The advantage is that the program can be started using RUN. - -To generate a program with a BASIC SYS header, use - -<tscreen><verb> -cl65 -o file.prg -u __EXEHDR__ -t c64 -C c64-asm.cfg source.s -</verb></tscreen> - -Please note that in this case a changed start address doesn't make sense, -since the program must be loaded to the BASIC start address. - - -<sect>Platform specific header files<p> - -Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/ -header files. Using the later may be an option when writing code for more than -one CBM platform, since it includes <tt/c64.h/ and declares several functions -common to all CBM platforms. - - -<sect1>C64 specific functions<p> - -The functions listed below are special for the C64. See the <htmlurl -url="funcref.html" name="function reference"> for declaration and usage. - -<itemize> -<item>get_ostype -</itemize> - - -<sect1>CBM specific functions<p> - -Some functions are available for all (or at least most) of the Commodore -machines. See the <htmlurl url="funcref.html" name="function reference"> for -declaration and usage. - -<itemize> -<item>cbm_close -<item>cbm_closedir -<item>cbm_k_setlfs -<item>cbm_k_setnam -<item>cbm_k_load -<item>cbm_k_save -<item>cbm_k_open -<item>cbm_k_close -<item>cbm_k_readst -<item>cbm_k_chkin -<item>cbm_k_ckout -<item>cbm_k_basin -<item>cbm_k_bsout -<item>cbm_k_clrch -<item>cbm_load -<item>cbm_open -<item>cbm_opendir -<item>cbm_read -<item>cbm_readdir -<item>cbm_save -<item>cbm_write -<item>get_tv -</itemize> - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/c64.h/ header file do allow -access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<descrip> - - <tag><tt/VIC/</tag> - The <tt/VIC/ structure allows access to the VIC II (the graphics - controller). See the <tt/_vic2.h/ header file located in the include - directory for the declaration of the structure. - - <tag><tt/SID/</tag> - The <tt/SID/ structure allows access to the SID (the sound interface - device). See the <tt/_sid.h/ header file located in the include directory - for the declaration of the structure. - - <tag><tt/CIA1, CIA2/</tag> - Access to the two CIA (complex interface adapter) chips is available via - the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables - is explained in <tt/_6526.h/. - - <tag><tt/COLOR_RAM/</tag> - A character array that mirrors the color RAM of the C64 at $D800. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -<em>Note:</em> All available graphics drivers for the TGI interface will use -the space below the I/O area and kernal ROM, so you can have hires graphics in -the standard setup without any memory loss or need for a changed -configuration. - -<descrip> - <tag><tt/c64-hi.tgi (c64_320_200_2)/</tag> - This driver features a resolution of 320*200 with two colors and an - adjustable palette (that means that the two colors can be chosen out of a - palette of the 16 C64 colors). -</descrip><p> - - -<sect1>Extended memory drivers<p> - -<descrip> - - <tag><tt/c64-c256k.emd (c64_c256k)/</tag> - A driver for the C64 256K memory expansion. This driver offers 768 pages of - 256 bytes each. Written and contributed by Marco van den Heuvel. - - <tag><tt/c64-dqbb.emd (c64_dqbb)/</tag> - A driver for the Double Quick Brown Box cartridge. This driver offers - 64 pages of 256 bytes each. Written and contributed by Marco van den Heuvel. - - <tag><tt/c64-georam.emd (c64_georam)/</tag> - A driver for the Berkeley Softworks GeoRam cartridge. The driver will - determine the available RAM from the connected cartridge. It supports 64KB - up to 2048KB of RAM. - - <tag><tt/c64-isepic.emd (c64_isepic)/</tag> - A driver for the ISEPIC cartridge. This driver offers just 8 pages of 256 - bytes each. Written and contributed by Marco van den Heuvel. - - <tag><tt/c64-ram.emd (c64_ram)/</tag> - A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48 - 256 byte pages. Please note that this driver is incompatible with any of the - graphics drivers! - - <tag><tt/c64-ramcart.emd (c64_ramcart)/</tag> - A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. - Will test the hardware for the available RAM. - - <tag><tt/c64-reu.emd (c64_reu)/</tag> - A driver for the CBM REUs. The driver will determine from the connected REU - if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, - but since there are no range checks, the application can use more memory if - it has better knowledge about the hardware than the driver. - - <tag><tt/c64-vdc.emd (c64_vdc)/</tag> - A driver for the VDC memory of the C128. Written and contributed by Maciej - Witkowiak. Can be used if the program is running in C64 mode of the C128. - Autodetects the amount of memory available (16 or 64K) and offers 64 or 256 - pages of 256 bytes each. - - <tag><tt/dtv-himem.emd (dtv_himem)/</tag> - A driver for the C64 D2TV (the second or PAL version). This driver offers - indeed 7680 pages of 256 bytes each. - -</descrip><p> - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/c64-hitjoy.joy (c64_hitjoy)/</tag> - Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See - <htmlurl url="http://www.digitalexcess.de/downloads/productions.php" - name="http://www.digitalexcess.de/downloads/productions.php"> on - instructions how to build one. Up to four joysticks are supported. - - <tag><tt/c64-ptvjoy.joy (c64_ptvjoy)/</tag> - Driver for the Protovision 4-player adapter contributed by Groepaz. See - <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" - name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and - building instructions. Up to four joysticks are supported. - - <tag><tt/c64-stdjoy.joy (c64_stdjoy)/</tag> - Supports up to two standard joysticks connected to the joysticks port of - the C64. - - <tag><tt/c64-numpad.joy (c64_numpad)/</tag> - Supports one joystick emulated by the numberpad of the C128 in C64 mode, - the firebutton is labeled &dquot;5&dquot; and ENTER. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -<descrip> - - <tag><tt/c64-1351.mou (c64_1351)/</tag> - Supports a standard mouse connected to port #0 of the C64. - - <tag><tt/c64-joy.mou (c64_joymouse)/</tag> - Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port - #1 of the C64. - - <tag><tt/c64-pot.mou (c64_potmouse)/</tag> - Supports a potentiometer device e.g. Koala Pad connected to port #1 of - the C64. - -</descrip><p> - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/c64-swlink.ser (c64_swlink)/</tag> - Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow - control (RTS/CTS) and interrupt driven receives. Note that because of the - peculiarities of the 6551 chip together with the use of the NMI, transmits - are not interrupt driven, and the transceiver blocks if the receiver asserts - flow control because of a full buffer. - -</descrip><p> - - - -<sect>Limitations<p> - - - -<sect>Other hints<p> - -<sect1>Escape code<p> - -For an Esc press CTRL and [ key. - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/. Since this is not -supported by BASIC, the following syntax was chosen: - -<tscreen><verb> - RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 -</verb></tscreen> - -<enum> -<item>Arguments are separated by spaces. -<item>Arguments may be quoted. -<item>Leading and trailing spaces around an argument are ignored. Spaces within - a quoted argument are allowed. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 10 arguments (including the program name) are - supported. -</enum> - - -<sect1>Program return code<p> - -The program return code (low byte) is passed back to BASIC by use of the -<tt/ST/ variable. - - -<sect1>Interrupts<p> - -The runtime for the C64 uses routines marked as <tt/.INTERRUPTOR/ for -interrupt handlers. Such routines must be written as simple machine language -subroutines and will be called automatically by the interrupt handler code -when they are linked into a program. See the discussion of the <tt/.CONDES/ -feature in the <htmlurl url="ca65.html" name="assembler manual">. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/ca65.sgml b/doc/ca65.sgml deleted file mode 100644 index 00d72db56..000000000 --- a/doc/ca65.sgml +++ /dev/null @@ -1,4786 +0,0 @@ -<!doctype linuxdoc system> <!-- -*- text-mode -*- --> - -<article> -<title>ca65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2000-07-19, 2000-11-29, 2001-10-02, 2005-09-08 - -<abstract> -ca65 is a powerful macro assembler for the 6502, 65C02 and 65816 CPUs. It is -used as a companion assembler for the cc65 crosscompiler, but it may also be -used as a standalone product. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -ca65 is a replacement for the ra65 assembler that was part of the cc65 C -compiler, originally developed by John R. Dunning. I had some problems with -ra65 and the copyright does not permit some things which I wanted to be -possible, so I decided to write a completely new assembler/linker/archiver -suite for the cc65 compiler. ca65 is part of this suite. - -Some parts of the assembler (code generation and some routines for symbol -table handling) are taken from an older crossassembler named a816 written -by me a long time ago. - - -<sect1>Design criteria<p> - -Here's a list of the design criteria, that I considered important for the -development: - -<itemize> - -<item> The assembler must support macros. Macros are not essential, but they - make some things easier, especially when you use the assembler in the - backend of a compiler. -<item> The assembler must support the newer 65C02 and 65816 CPUs. I have been - thinking about a 65816 backend for the C compiler, and even my old - a816 assembler had support for these CPUs, so this wasn't really a - problem. -<item> The assembler must produce relocatable code. This is necessary for the - compiler support, and it is more convenient. -<item> Conditional assembly must be supported. This is a must for bigger - projects written in assembler (like Elite128). -<item> The assembler must support segments, and it must support more than - three segments (this is the count, most other assemblers support). - Having more than one code segments helps developing code for systems - with a divided ROM area (like the C64). -<item> The linker must be able to resolve arbitrary expressions. It should - be able to get things like -<tscreen><verb> - .import S1, S2 - .export Special - Special = 2*S1 + S2/7 -</verb></tscreen> - right. -<item> True lexical nesting for symbols. This is very convenient for larger - assembly projects. -<item> "Cheap" local symbols without lexical nesting for those quick, late - night hacks. -<item> I liked the idea of "options" as Anre Fachats .o65 format has it, so I - introduced the concept into the object file format use by the new cc65 - binutils. -<item> The assembler will be a one pass assembler. There was no real need for - this decision, but I've written several multipass assemblers, and it - started to get boring. A one pass assembler needs much more elaborated - data structures, and because of that it's much more fun:-) -<item> Non-GPLed code that may be used in any project without restrictions or - fear of "GPL infecting" other code. -</itemize> -<p> - - -<sect>Usage<p> - - -<sect1>Command line option overview<p> - -The assembler accepts the following options: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: ca65 [options] file -Short options: - -D name[=value] Define a symbol - -I dir Set an include directory search path - -U Mark unresolved symbols as import - -V Print the assembler version - -W n Set warning level n - -d Debug mode - -g Add debug info to object file - -h Help (this text) - -i Ignore case of symbols - -l name Create a listing file if assembly was ok - -mm model Set the memory model - -o name Name the output file - -s Enable smart mode - -t sys Set the target system - -v Increase verbosity - -Long options: - --auto-import Mark unresolved symbols as import - --bin-include-dir dir Set a search path for binary includes - --cpu type Set cpu type - --create-dep name Create a make dependency file - --create-full-dep name Create a full make dependency file - --debug Debug mode - --debug-info Add debug info to object file - --feature name Set an emulation feature - --forget-inc-paths Forget include search paths - --help Help (this text) - --ignore-case Ignore case of symbols - --include-dir dir Set an include directory search path - --large-alignment Don't warn about large alignments - --listing name Create a listing file if assembly was ok - --list-bytes n Maximum number of bytes per listing line - --macpack-dir dir Set a macro package directory - --memory-model model Set the memory model - --pagelength n Set the page length for the listing - --relax-checks Relax some checks (see docs) - --smart Enable smart mode - --target sys Set the target system - --verbose Increase verbosity - --version Print the assembler version ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<p> - -Here is a description of all the command line options: - -<descrip> - - <label id="option--bin-include-dir"> - <tag><tt>--bin-include-dir dir</tt></tag> - - Name a directory which is searched for binary include files. The option - may be used more than once to specify more than one directory to search. The - current directory is always searched first before considering any - additional directories. See also the section about <ref id="search-paths" - name="search paths">. - - - <label id="option--cpu"> - <tag><tt>--cpu type</tt></tag> - - Set the default for the CPU type. The option takes a parameter, which - may be one of - - 6502, 65SC02, 65C02, 65816, sunplus, sweet16, HuC6280 - - The sunplus cpu is not available in the freeware version, because the - instruction set is "proprietary and confidential". - - - <label id="option-create-dep"> - <tag><tt>--create-dep name</tt></tag> - - Tells the assembler to generate a file containing the dependency list for - the assembled module in makefile syntax. The output is written to a file - with the given name. The output does not include files passed via debug - information to the assembler. - - - <label id="option-create-full-dep"> - <tag><tt>--create-full-dep name</tt></tag> - - Tells the assembler to generate a file containing the dependency list for - the assembled module in makefile syntax. The output is written to a file - with the given name. The output does include files passed via debug - information to the assembler. - - - <tag><tt>-d, --debug</tt></tag> - - Enables debug mode, something that should not be needed for mere - mortals:-) - - - <label id="option--feature"> - <tag><tt>--feature name</tt></tag> - - Enable an emulation feature. This is identical as using <tt/.FEATURE/ - in the source with two exceptions: Feature names must be lower case, and - each feature must be specified by using an extra <tt/--feature/ option, - comma separated lists are not allowed. - - See the discussion of the <tt><ref id=".FEATURE" name=".FEATURE"></tt> - command for a list of emulation features. - - - <label id="option--forget-inc-paths"> - <tag><tt>--forget-inc-paths</tt></tag> - - Forget the builtin include paths. This is most useful when building - customized assembler modules, in which case the standard header files should - be ignored. - - - <label id="option-g"> - <tag><tt>-g, --debug-info</tt></tag> - - When this option (or the equivalent control command <tt/.DEBUGINFO/) is - used, the assembler will add a section to the object file that contains - all symbols (including local ones) together with the symbol values and - source file positions. The linker will put these additional symbols into - the VICE label file, so even local symbols can be seen in the VICE - monitor. - - - <label id="option-h"> - <tag><tt>-h, --help</tt></tag> - - Print the short option summary shown above. - - - <label id="option-i"> - <tag><tt>-i, --ignore-case</tt></tag> - - This option makes the assembler case insensitive on identifiers and labels. - This option will override the default, but may itself be overridden by the - <tt><ref id=".CASE" name=".CASE"></tt> control command. - - - <label id="option-l"> - <tag><tt>-l name, --listing name</tt></tag> - - Generate an assembler listing with the given name. A listing file will - never be generated in case of assembly errors. - - - <label id="option--large-alignment"> - <tag><tt>--large-alignment</tt></tag> - - Disable warnings about a large combined alignment. See the discussion of the - <tt><ref id=".ALIGN" name=".ALIGN"></tt> directive for futher information. - - - <label id="option--list-bytes"> - <tag><tt>--list-bytes n</tt></tag> - - Set the maximum number of bytes printed in the listing for one line of - input. See the <tt><ref id=".LISTBYTES" name=".LISTBYTES"></tt> directive - for more information. The value zero can be used to encode an unlimited - number of printed bytes. - - - <label id="option--macpack-dir"> - <tag><tt>--macpack-dir dir</tt></tag> - - This options allows to specify a directory containing macro files that are - used instead of the builtin images when a <tt><ref id=".MACPACK" - name=".MACPACK"></tt> directive is encountered. If <tt>--macpack-dir</tt> - was specified, a <tt>.mac</tt> extension is added to the package name and - the resulting file is loaded from the given directory. This is most useful - when debugging the builtin macro packages. - - - <label id="option-mm"> - <tag><tt>-mm model, --memory-model model</tt></tag> - - Define the default memory model. Possible model specifiers are near, far and - huge. - - - <label id="option-o"> - <tag><tt>-o name</tt></tag> - - The default output name is the name of the input file with the extension - replaced by ".o". If you don't like that, you may give another name with - the -o option. The output file will be placed in the same directory as - the source file, or, if -o is given, the full path in this name is used. - - - <label id="option--pagelength"> - <tag><tt>--pagelength n</tt></tag> - - sets the length of a listing page in lines. See the <tt><ref - id=".PAGELENGTH" name=".PAGELENGTH"></tt> directive for more information. - - - <label id="option--relax-checks"> - <tag><tt>--relax-checks</tt></tag> - - Relax some checks done by the assembler. This will allow code that is an - error in most cases and flagged as such by the assembler, but can be valid - in special situations. - - Examples are: -<itemize> -<item>Short branches between two different segments. -<item>Byte sized address loads where the address is not a zeropage address. -</itemize> - - - <label id="option-s"> - <tag><tt>-s, --smart-mode</tt></tag> - - In smart mode (enabled by -s or the <tt><ref id=".SMART" name=".SMART"></tt> - pseudo instruction) the assembler will track usage of the <tt/REP/ and - <tt/SEP/ instructions in 65816 mode and update the operand sizes - accordingly. If the operand of such an instruction cannot be evaluated by - the assembler (for example, because the operand is an imported symbol), a - warning is issued. - - Beware: Since the assembler cannot trace the execution flow this may - lead to false results in some cases. If in doubt, use the .ixx and .axx - instructions to tell the assembler about the current settings. Smart - mode is off by default. - - - <label id="option-t"> - <tag><tt>-t sys, --target sys</tt></tag> - - Set the target system. This will enable translation of character strings and - character constants into the character set of the target platform. The - default for the target system is "none", which means that no translation - will take place. The assembler supports the same target systems as the - compiler, see there for a list. - - Depending on the target, the default CPU type is also set. This can be - overriden by using the <tt/<ref id="option--cpu" name="--cpu">/ option. - - - <label id="option-v"> - <tag><tt>-v, --verbose</tt></tag> - - Increase the assembler verbosity. Usually only needed for debugging - purposes. You may use this option more than one time for even more - verbose output. - - - <label id="option-D"> - <tag><tt>-D</tt></tag> - - This option allows you to define symbols on the command line. Without a - value, the symbol is defined with the value zero. When giving a value, - you may use the '$' prefix for hexadecimal symbols. Please note - that for some operating systems, '$' has a special meaning, so - you may have to quote the expression. - - - <label id="option-I"> - <tag><tt>-I dir, --include-dir dir</tt></tag> - - Name a directory which is searched for include files. The option may be - used more than once to specify more than one directory to search. The - current directory is always searched first before considering any - additional directories. See also the section about <ref id="search-paths" - name="search paths">. - - - <label id="option-U"> - <tag><tt>-U, --auto-import</tt></tag> - - Mark symbols that are not defined in the sources as imported symbols. This - should be used with care since it delays error messages about typos and such - until the linker is run. The compiler uses the equivalent of this switch - (<tt><ref id=".AUTOIMPORT" name=".AUTOIMPORT"></tt>) to enable auto imported - symbols for the runtime library. However, the compiler is supposed to - generate code that runs through the assembler without problems, something - which is not always true for assembler programmers. - - - <label id="option-V"> - <tag><tt>-V, --version</tt></tag> - - Print the version number of the assembler. If you send any suggestions - or bugfixes, please include the version number. - - - <label id="option-W"> - <tag><tt>-Wn</tt></tag> - - Set the warning level for the assembler. Using -W2 the assembler will - even warn about such things like unused imported symbols. The default - warning level is 1, and it would probably be silly to set it to - something lower. - -</descrip> -<p> - - - -<sect>Search paths<label id="search-paths"><p> - -Normal include files are searched in the following places: - -<enum> -<item>The current directory. -<item>A compiled-in directory, which is often <tt>/usr/lib/cc65/asminc</tt> - on Linux systems. -<item>The value of the environment variable <tt/CA65_INC/ if it is defined. -<item>A subdirectory named <tt/asminc/ of the directory defined in the - environment variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt/<ref id="option-I" name="-I">/ option -on the command line. -</enum> - -Binary include files are searched in the following places: - -<enum> -<item>The current directory. -<item>Any directory added with the <tt/<ref id="option--bin-include-dir" -name="--bin-include-dir">/ option on the command line. -</enum> - - - -<sect>Input format<p> - -<sect1>Assembler syntax<p> - -The assembler accepts the standard 6502/65816 assembler syntax. One line may -contain a label (which is identified by a colon), and, in addition to the -label, an assembler mnemonic, a macro, or a control command (see section <ref -id="control-commands" name="Control Commands"> for supported control -commands). Alternatively, the line may contain a symbol definition using -the '=' token. Everything after a semicolon is handled as a comment (that is, -it is ignored). - -Here are some examples for valid input lines: - -<tscreen><verb> - Label: ; A label and a comment - lda #$20 ; A 6502 instruction plus comment - L1: ldx #$20 ; Same with label - L2: .byte "Hello world" ; Label plus control command - mymac $20 ; Macro expansion - MySym = 3*L1 ; Symbol definition - MaSym = Label ; Another symbol -</verb></tscreen> - -The assembler accepts - -<itemize> -<item>all valid 6502 mnemonics when in 6502 mode (the default or after the - <tt><ref id=".P02" name=".P02"></tt> command was given). -<item>all valid 6502 mnemonics plus a set of illegal instructions when in - <ref id="6502X-mode" name="6502X mode">. -<item>all valid 65SC02 mnemonics when in 65SC02 mode (after the - <tt><ref id=".PSC02" name=".PSC02"></tt> command was given). -<item>all valid 65C02 mnemonics when in 65C02 mode (after the - <tt><ref id=".PC02" name=".PC02"></tt> command was given). -<item>all valid 65618 mnemonics when in 65816 mode (after the - <tt><ref id=".P816" name=".P816"></tt> command was given). -<item>all valid SunPlus mnemonics when in SunPlus mode (after the - <tt><ref id=".SUNPLUS" name=".SUNPLUS"></tt> command was given). -</itemize> - - -<sect1>65816 mode<p> - -In 65816 mode several aliases are accepted in addition to the official -mnemonics: - -<tscreen><verb> - BGE is an alias for BCS - BLT is an alias for BCC - CPA is an alias for CMP - DEA is an alias for DEC A - INA is an alias for INC A - SWA is an alias for XBA - TAD is an alias for TCD - TAS is an alias for TCS - TDA is an alias for TDC - TSA is an alias for TSC -</verb></tscreen> - - - -<sect1>6502X mode<label id="6502X-mode"><p> - -6502X mode is an extension to the normal 6502 mode. In this mode, several -mnemonics for illegal instructions of the NMOS 6502 CPUs are accepted. Since -these instructions are illegal, there are no official mnemonics for them. The -unofficial ones are taken from <htmlurl -url="http://www.oxyron.de/html/opcodes02.html" -name="http://www.oxyron.de/html/opcodes02.html">. Please note that only the -ones marked as "stable" are supported. The following table uses information -from the mentioned web page, for more information, see there. - -<itemize> -<item><tt>ALR: A:=(A and #{imm})/2;</tt> -<item><tt>ANC: A:=A and #{imm};</tt> Generates opcode $0B. -<item><tt>ARR: A:=(A and #{imm})/2;</tt> -<item><tt>AXS: X:=A and X-#{imm};</tt> -<item><tt>DCP: {adr}:={adr}-1; A-{adr};</tt> -<item><tt>ISC: {adr}:={adr}+1; A:=A-{adr};</tt> -<item><tt>LAS: A,X,S:={adr} and S;</tt> -<item><tt>LAX: A,X:={adr};</tt> -<item><tt>RLA: {adr}:={adr}rol; A:=A and {adr};</tt> -<item><tt>RRA: {adr}:={adr}ror; A:=A adc {adr};</tt> -<item><tt>SAX: {adr}:=A and X;</tt> -<item><tt>SLO: {adr}:={adr}*2; A:=A or {adr};</tt> -<item><tt>SRE: {adr}:={adr}/2; A:=A xor {adr};</tt> -</itemize> - - - -<sect1>sweet16 mode<label id="sweet16-mode"><p> - -SWEET 16 is an interpreter for a pseudo 16 bit CPU written by Steve Wozniak -for the Apple ][ machines. It is available in the Apple ][ ROM. ca65 can -generate code for this pseudo CPU when switched into sweet16 mode. The -following is special in sweet16 mode: - -<itemize> - -<item>The '@' character denotes indirect addressing and is no longer available -for cheap local labels. If you need cheap local labels, you will have to -switch to another lead character using the <tt/<ref id=".LOCALCHAR" -name=".LOCALCHAR">/ command. - -<item>Registers are specified using <tt/R0/ .. <tt/R15/. In sweet16 mode, -these identifiers are reserved words. - -</itemize> - -Please note that the assembler does neither supply the interpreter needed for -SWEET 16 code, nor the zero page locations needed for the SWEET 16 registers, -nor does it call the interpreter. All this must be done by your program. Apple -][ programmers do probably know how to use sweet16 mode. - -For more information about SWEET 16, see -<htmlurl url="http://www.6502.org/source/interpreters/sweet16.htm" -name="http://www.6502.org/source/interpreters/sweet16.htm">. - - -<sect1>Number format<p> - -For literal values, the assembler accepts the widely used number formats: A -preceding '$' or a trailing 'h' denotes a hex value, a preceding '%' -denotes a binary value, and a bare number is interpreted as a decimal. There -are currently no octal values and no floats. - - -<sect1>Conditional assembly<p> - -Please note that when using the conditional directives (<tt/.IF/ and friends), -the input must consist of valid assembler tokens, even in <tt/.IF/ branches -that are not assembled. The reason for this behaviour is that the assembler -must still be able to detect the ending tokens (like <tt/.ENDIF/), so -conversion of the input stream into tokens still takes place. As a consequence -conditional assembly directives may <bf/not/ be used to prevent normal text -(used as a comment or similar) from being assembled. <p> - - -<sect>Expressions<p> - - -<sect1>Expression evaluation<p> - -All expressions are evaluated with (at least) 32 bit precision. An -expression may contain constant values and any combination of internal and -external symbols. Expressions that cannot be evaluated at assembly time -are stored inside the object file for evaluation by the linker. -Expressions referencing imported symbols must always be evaluated by the -linker. - - -<sect1>Size of an expression result<p> - -Sometimes, the assembler must know about the size of the value that is the -result of an expression. This is usually the case, if a decision has to be -made, to generate a zero page or an absolute memory references. In this -case, the assembler has to make some assumptions about the result of an -expression: - -<itemize> -<item> If the result of an expression is constant, the actual value is - checked to see if it's a byte sized expression or not. -<item> If the expression is explicitly casted to a byte sized expression by - one of the '>', '<' or '^' operators, it is a byte expression. -<item> If this is not the case, and the expression contains a symbol, - explicitly declared as zero page symbol (by one of the .importzp or - .exportzp instructions), then the whole expression is assumed to be - byte sized. -<item> If the expression contains symbols that are not defined, and these - symbols are local symbols, the enclosing scopes are searched for a - symbol with the same name. If one exists and this symbol is defined, - its attributes are used to determine the result size. -<item> In all other cases the expression is assumed to be word sized. -</itemize> - -Note: If the assembler is not able to evaluate the expression at assembly -time, the linker will evaluate it and check for range errors as soon as -the result is known. - - -<sect1>Boolean expressions<p> - -In the context of a boolean expression, any non zero value is evaluated as -true, any other value to false. The result of a boolean expression is 1 if -it's true, and zero if it's false. There are boolean operators with extreme -low precedence with version 2.x (where x > 0). The <tt/.AND/ and <tt/.OR/ -operators are shortcut operators. That is, if the result of the expression is -already known, after evaluating the left hand side, the right hand side is -not evaluated. - - -<sect1>Constant expressions<p> - -Sometimes an expression must evaluate to a constant without looking at any -further input. One such example is the <tt/<ref id=".IF" name=".IF">/ command -that decides if parts of the code are assembled or not. An expression used in -the <tt/.IF/ command cannot reference a symbol defined later, because the -decision about the <tt/.IF/ must be made at the point when it is read. If the -expression used in such a context contains only constant numerical values, -there is no problem. When unresolvable symbols are involved it may get harder -for the assembler to determine if the expression is actually constant, and it -is even possible to create expressions that aren't recognized as constant. -Simplifying the expressions will often help. - -In cases where the result of the expression is not needed immediately, the -assembler will delay evaluation until all input is read, at which point all -symbols are known. So using arbitrary complex constant expressions is no -problem in most cases. - - - -<sect1>Available operators<label id="operators"><p> - -<table> -<tabular ca="clc"> -<bf/Operator/| <bf/Description/| <bf/Precedence/@<hline> -| Built-in string functions| 0@ -||~@ -| Built-in pseudo-variables| 1@ -| Built-in pseudo-functions| 1@ -+| Unary positive| 1@ --| Unary negative| 1@ -˜<newline> -.BITNOT| Unary bitwise not| 1@ -<<newline> -.LOBYTE| Unary low-byte operator| 1@ -><newline> -.HIBYTE| Unary high-byte operator| 1@ -^<newline> -.BANKBYTE| Unary bank-byte operator| 1@ -||~@ -*| Multiplication| 2@ -/| Division| 2@ -.MOD| Modulo operator| 2@ -&<newline> -.BITAND| Bitwise and| 2@ -^<newline> -.BITXOR| Binary bitwise xor| 2@ -<<<newline> -.SHL| Shift-left operator| 2@ ->><newline> -.SHR| Shift-right operator| 2@ -||~@ -+| Binary addition| 3@ --| Binary subtraction| 3@ -|<newline> -.BITOR| Bitwise or| 3@ -||~@ -= | Compare operator (equal)| 4@ -<>| Compare operator (not equal)| 4@ -<| Compare operator (less)| 4@ ->| Compare operator (greater)| 4@ -<=| Compare operator (less or equal)| 4@ ->=| Compare operator (greater or equal)| 4@ -||~@ -&&<newline> -.AND| Boolean and| 5@ -.XOR| Boolean xor| 5@ -||~@ -||<newline> -.OR| Boolean or| 6@ -||~@ -!<newline> -.NOT| Boolean not| 7@<hline> -</tabular> -<caption>Available operators, sorted by precedence -</table> - -To force a specific order of evaluation, parentheses may be used, as usual. - - - -<sect>Symbols and labels<p> - -A symbol or label is an identifier that starts with a letter and is followed -by letters and digits. Depending on some features enabled (see -<tt><ref id="at_in_identifiers" name="at_in_identifiers"></tt>, -<tt><ref id="dollar_in_identifiers" name="dollar_in_identifiers"></tt> and -<tt><ref id="leading_dot_in_identifiers" name="leading_dot_in_identifiers"></tt>) -other characters may be present. Use of identifiers consisting of a single -character will not work in all cases, because some of these identifiers are -reserved keywords (for example "A" is not a valid identifier for a label, -because it is the keyword for the accumulator). - -The assembler allows you to use symbols instead of naked values to make -the source more readable. There are a lot of different ways to define and -use symbols and labels, giving a lot of flexibility. - -<sect1>Numeric constants<p> - -Numeric constants are defined using the equal sign or the label assignment -operator. After doing - -<tscreen><verb> - two = 2 -</verb></tscreen> - -may use the symbol "two" in every place where a number is expected, and it is -evaluated to the value 2 in this context. The label assignment operator is -almost identical, but causes the symbol to be marked as a label, so it may be -handled differently in a debugger: - -<tscreen><verb> - io := $d000 -</verb></tscreen> - -The right side can of course be an expression: - -<tscreen><verb> - four = two * two -</verb></tscreen> - - -<label id="variables"> -<sect1>Numeric variables<p> - -Within macros and other control structures (<tt><ref id=".REPEAT" -name=".REPEAT"></tt>, ...) it is sometimes useful to have some sort of -variable. This can be achieved by the <tt>.SET</tt> operator. It creates a -symbol that may get assigned a different value later: - -<tscreen><verb> - four .set 4 - lda #four ; Loads 4 into A - four .set 3 - lda #four ; Loads 3 into A -</verb></tscreen> - -Since the value of the symbol can change later, it must be possible to -evaluate it when used (no delayed evaluation as with normal symbols). So the -expression used as the value must be constant. - -Following is an example for a macro that generates a different label each time -it is used. It uses the <tt><ref id=".SPRINTF" name=".SPRINTF"></tt> function -and a numeric variable named <tt>lcount</tt>. - -<tscreen><verb> - .lcount .set 0 ; Initialize the counter - - .macro genlab - .ident (.sprintf ("L%04X", lcount)): - lcount .set lcount + 1 - .endmacro -</verb></tscreen> - - -<sect1>Standard labels<p> - -A label is defined by writing the name of the label at the start of the line -(before any instruction mnemonic, macro or pseudo directive), followed by a -colon. This will declare a symbol with the given name and the value of the -current program counter. - - -<sect1>Local labels and symbols<p> - -Using the <tt><ref id=".PROC" name=".PROC"></tt> directive, it is possible to -create regions of code where the names of labels and symbols are local to this -region. They are not known outside of this region and cannot be accessed from -there. Such regions may be nested like PROCEDUREs in Pascal. - -See the description of the <tt><ref id=".PROC" name=".PROC"></tt> -directive for more information. - - -<sect1>Cheap local labels<p> - -Cheap local labels are defined like standard labels, but the name of the -label must begin with a special symbol (usually '@', but this can be -changed by the <tt><ref id=".LOCALCHAR" name=".LOCALCHAR"></tt> -directive). - -Cheap local labels are visible only between two non cheap labels. As soon as a -standard symbol is encountered (this may also be a local symbol if inside a -region defined with the <tt><ref id=".PROC" name=".PROC"></tt> directive), the -cheap local symbol goes out of scope. - -You may use cheap local labels as an easy way to reuse common label -names like "Loop". Here is an example: - -<tscreen><verb> - Clear: lda #$00 ; Global label - ldy #$20 - @Loop: sta Mem,y ; Local label - dey - bne @Loop ; Ok - rts - Sub: ... ; New global label - bne @Loop ; ERROR: Unknown identifier! -</verb></tscreen> - -<sect1>Unnamed labels<p> - -If you really want to write messy code, there are also unnamed labels. These -labels do not have a name (you guessed that already, didn't you?). A colon is -used to mark the absence of the name. - -Unnamed labels may be accessed by using the colon plus several minus or plus -characters as a label designator. Using the '-' characters will create a back -reference (use the n'th label backwards), using '+' will create a forward -reference (use the n'th label in forward direction). An example will help to -understand this: - -<tscreen><verb> - : lda (ptr1),y ; #1 - cmp (ptr2),y - bne :+ ; -> #2 - tax - beq :+++ ; -> #4 - iny - bne :- ; -> #1 - inc ptr1+1 - inc ptr2+1 - bne :- ; -> #1 - - : bcs :+ ; #2 -> #3 - ldx #$FF - rts - - : ldx #$01 ; #3 - : rts ; #4 -</verb></tscreen> - -As you can see from the example, unnamed labels will make even short -sections of code hard to understand, because you have to count labels -to find branch targets (this is the reason why I for my part do -prefer the "cheap" local labels). Nevertheless, unnamed labels are -convenient in some situations, so it's your decision. - -<bf/Note:/ <ref id="scopes" name="Scopes"> organize named symbols, not -unnamed ones, so scopes don't have an effect on unnamed labels. - - - -<sect1>Using macros to define labels and constants<p> - -While there are drawbacks with this approach, it may be handy in a few rare -situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is possible -to define symbols or constants that may be used elsewhere. One of the -advantages is that you can use it to define string constants (this is not -possible with the other symbol types). - -Please note: <tt/.DEFINE/ style macros do token replacements on a low level, -so the names do not adhere to scoping, diagnostics may be misleading, there -are no symbols to look up in the map file, and there is no debug info. -Especially the first problem in the list can lead to very nasty programming -errors. Because of these problems, the general advice is, <bf/NOT/ do use -<tt/.DEFINE/ if you don't have to. - -Example: - -<tscreen><verb> - .DEFINE two 2 - .DEFINE version "SOS V2.3" - - four = two * two ; Ok - .byte version ; Ok - - .PROC ; Start local scope - two = 3 ; Will give "2 = 3" - invalid! - .ENDPROC -</verb></tscreen> - - -<sect1>Symbols and <tt>.DEBUGINFO</tt><p> - -If <tt><ref id=".DEBUGINFO" name=".DEBUGINFO"></tt> is enabled (or <ref -id="option-g" name="-g"> is given on the command line), global, local and -cheap local labels are written to the object file and will be available in the -symbol file via the linker. Unnamed labels are not written to the object file, -because they don't have a name which would allow to access them. - - - -<sect>Scopes<label id="scopes"><p> - -ca65 implements several sorts of scopes for symbols. - -<sect1>Global scope<p> - -All (non cheap local) symbols that are declared outside of any nested scopes -are in global scope. - - -<sect1>Cheap locals<p> - -A special scope is the scope for cheap local symbols. It lasts from one non -local symbol to the next one, without any provisions made by the programmer. -All other scopes differ in usage but use the same concept internally. - - -<sect1>Generic nested scopes<p> - -A nested scoped for generic use is started with <tt/<ref id=".SCOPE" -name=".SCOPE">/ and closed with <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/. -The scope can have a name, in which case it is accessible from the outside by -using <ref id="scopesyntax" name="explicit scopes">. If the scope does not -have a name, all symbols created within the scope are local to the scope, and -aren't accessible from the outside. - -A nested scope can access symbols from the local or from enclosing scopes by -name without using explicit scope names. In some cases there may be -ambiguities, for example if there is a reference to a local symbol that is not -yet defined, but a symbol with the same name exists in outer scopes: - -<tscreen><verb> - .scope outer - foo = 2 - .scope inner - lda #foo - foo = 3 - .endscope - .endscope -</verb></tscreen> - -In the example above, the <tt/lda/ instruction will load the value 3 into the -accumulator, because <tt/foo/ is redefined in the scope. However: - -<tscreen><verb> - .scope outer - foo = $1234 - .scope inner - lda foo,x - foo = $12 - .endscope - .endscope -</verb></tscreen> - -Here, <tt/lda/ will still load from <tt/$12,x/, but since it is unknown to the -assembler that <tt/foo/ is a zeropage symbol when translating the instruction, -absolute mode is used instead. In fact, the assembler will not use absolute -mode by default, but it will search through the enclosing scopes for a symbol -with the given name. If one is found, the address size of this symbol is used. -This may lead to errors: - -<tscreen><verb> - .scope outer - foo = $12 - .scope inner - lda foo,x - foo = $1234 - .endscope - .endscope -</verb></tscreen> - -In this case, when the assembler sees the symbol <tt/foo/ in the <tt/lda/ -instruction, it will search for an already defined symbol <tt/foo/. It will -find <tt/foo/ in scope <tt/outer/, and a close look reveals that it is a -zeropage symbol. So the assembler will use zeropage addressing mode. If -<tt/foo/ is redefined later in scope <tt/inner/, the assembler tries to change -the address in the <tt/lda/ instruction already translated, but since the new -value needs absolute addressing mode, this fails, and an error message "Range -error" is output. - -Of course the most simple solution for the problem is to move the definition -of <tt/foo/ in scope <tt/inner/ upwards, so it precedes its use. There may be -rare cases when this cannot be done. In these cases, you can use one of the -address size override operators: - -<tscreen><verb> - .scope outer - foo = $12 - .scope inner - lda a:foo,x - foo = $1234 - .endscope - .endscope -</verb></tscreen> - -This will cause the <tt/lda/ instruction to be translated using absolute -addressing mode, which means changing the symbol reference later does not -cause any errors. - - -<sect1>Nested procedures<p> - -A nested procedure is created by use of <tt/<ref id=".PROC" name=".PROC">/. It -differs from a <tt/<ref id=".SCOPE" name=".SCOPE">/ in that it must have a -name, and a it will introduce a symbol with this name in the enclosing scope. -So - -<tscreen><verb> - .proc foo - ... - .endproc -</verb></tscreen> - -is actually the same as - -<tscreen><verb> - foo: - .scope foo - ... - .endscope -</verb></tscreen> - -This is the reason why a procedure must have a name. If you want a scope -without a name, use <tt/<ref id=".SCOPE" name=".SCOPE">/. - -<bf/Note:/ As you can see from the example above, scopes and symbols live in -different namespaces. There can be a symbol named <tt/foo/ and a scope named -<tt/foo/ without any conflicts (but see the section titled <ref -id="scopesearch" name=""Scope search order"">). - - -<sect1>Structs, unions and enums<p> - -Structs, unions and enums are explained in a <ref id="structs" name="separate -section">, I do only cover them here, because if they are declared with a -name, they open a nested scope, similar to <tt/<ref id=".SCOPE" -name=".SCOPE">/. However, when no name is specified, the behaviour is -different: In this case, no new scope will be opened, symbols declared within -a struct, union, or enum declaration will then be added to the enclosing scope -instead. - - -<sect1>Explicit scope specification<label id="scopesyntax"><p> - -Accessing symbols from other scopes is possible by using an explicit scope -specification, provided that the scope where the symbol lives in has a name. -The namespace token (<tt/::/) is used to access other scopes: - -<tscreen><verb> - .scope foo - bar: .word 0 - .endscope - - ... - lda foo::bar ; Access foo in scope bar -</verb></tscreen> - -The only way to deny access to a scope from the outside is to declare a scope -without a name (using the <tt/<ref id=".SCOPE" name=".SCOPE">/ command). - -A special syntax is used to specify the global scope: If a symbol or scope is -preceded by the namespace token, the global scope is searched: - -<tscreen><verb> - bar = 3 - - .scope foo - bar = 2 - lda #::bar ; Access the global bar (which is 3) - .endscope -</verb></tscreen> - - -<sect1>Scope search order<label id="scopesearch"><p> - -The assembler searches for a scope in a similar way as for a symbol. First, it -looks in the current scope, and then it walks up the enclosing scopes until -the scope is found. - -However, one important thing to note when using explicit scope syntax is, that -a symbol may be accessed before it is defined, but a scope may <bf/not/ be -used without a preceding definition. This means that in the following -example: - -<tscreen><verb> - .scope foo - bar = 3 - .endscope - - .scope outer - lda #foo::bar ; Will load 3, not 2! - .scope foo - bar = 2 - .endscope - .endscope -</verb></tscreen> - -the reference to the scope <tt/foo/ will use the global scope, and not the -local one, because the local one is not visible at the point where it is -referenced. - -Things get more complex if a complete chain of scopes is specified: - -<tscreen><verb> - .scope foo - .scope outer - .scope inner - bar = 1 - .endscope - .endscope - .scope another - .scope nested - lda #outer::inner::bar ; 1 - .endscope - .endscope - .endscope - - .scope outer - .scope inner - bar = 2 - .endscope - .endscope -</verb></tscreen> - -When <tt/outer::inner::bar/ is referenced in the <tt/lda/ instruction, the -assembler will first search in the local scope for a scope named <tt/outer/. -Since none is found, the enclosing scope (<tt/another/) is checked. There is -still no scope named <tt/outer/, so scope <tt/foo/ is checked, and finally -scope <tt/outer/ is found. Within this scope, <tt/inner/ is searched, and in -this scope, the assembler looks for a symbol named <tt/bar/. - -Please note that once the anchor scope is found, all following scopes -(<tt/inner/ in this case) are expected to be found exactly in this scope. The -assembler will search the scope tree only for the first scope (if it is not -anchored in the root scope). Starting from there on, there is no flexibility, -so if the scope named <tt/outer/ found by the assembler does not contain a -scope named <tt/inner/, this would be an error, even if such a pair does exist -(one level up in global scope). - -Ambiguities that may be introduced by this search algorithm may be removed by -anchoring the scope specification in the global scope. In the example above, -if you want to access the "other" symbol <tt/bar/, you would have to write: - -<tscreen><verb> - .scope foo - .scope outer - .scope inner - bar = 1 - .endscope - .endscope - .scope another - .scope nested - lda #::outer::inner::bar ; 2 - .endscope - .endscope - .endscope - - .scope outer - .scope inner - bar = 2 - .endscope - .endscope -</verb></tscreen> - - -<sect>Address sizes and memory models<label id="address-sizes"><p> - -<sect1>Address sizes<p> - -ca65 assigns each segment and each symbol an address size. This is true, even -if the symbol is not used as an address. You may also think of a value range -of the symbol instead of an address size. - -Possible address sizes are: - -<itemize> -<item>Zeropage or direct (8 bits) -<item>Absolute (16 bits) -<item>Far (24 bits) -<item>Long (32 bits) -</itemize> - -Since the assembler uses default address sizes for the segments and symbols, -it is usually not necessary to override the default behaviour. In cases, where -it is necessary, the following keywords may be used to specify address sizes: - -<itemize> -<item>DIRECT, ZEROPAGE or ZP for zeropage addressing (8 bits). -<item>ABSOLUTE, ABS or NEAR for absolute addressing (16 bits). -<item>FAR for far addressing (24 bits). -<item>LONG or DWORD for long addressing (32 bits). -</itemize> - - -<sect1>Address sizes of segments<p> - -The assembler assigns an address size to each segment. Since the -representation of a label within this segment is "segment start + offset", -labels will inherit the address size of the segment they are declared in. - -The address size of a segment may be changed, by using an optional address -size modifier. See the <tt/<ref id=".SEGMENT" name="segment directive">/ for -an explanation on how this is done. - - -<sect1>Address sizes of symbols<p> - - - - -<sect1>Memory models<p> - -The default address size of a segment depends on the memory model used. Since -labels inherit the address size from the segment they are declared in, -changing the memory model is an easy way to change the address size of many -symbols at once. - - - - -<sect>Pseudo variables<label id="pseudo-variables"><p> - -Pseudo variables are readable in all cases, and in some special cases also -writable. - -<sect1><tt>*</tt><p> - - Reading this pseudo variable will return the program counter at the start - of the current input line. - - Assignment to this variable is possible when <tt/<ref id=".FEATURE" - name=".FEATURE pc_assignment">/ is used. Note: You should not use - assignments to <tt/*/, use <tt/<ref id=".ORG" name=".ORG">/ instead. - - -<sect1><tt>.CPU</tt><label id=".CPU"><p> - - Reading this pseudo variable will give a constant integer value that - tells which CPU is currently enabled. It can also tell which instruction - set the CPU is able to translate. The value read from the pseudo variable - should be further examined by using one of the constants defined by the - "cpu" macro package (see <tt/<ref id=".MACPACK" name=".MACPACK">/). - - It may be used to replace the .IFPxx pseudo instructions or to construct - even more complex expressions. - - Example: - - <tscreen><verb> - .macpack cpu - .if (.cpu .bitand CPU_ISET_65816) - phx - phy - .else - txa - pha - tya - pha - .endif - </verb></tscreen> - - -<sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p> - - This builtin pseudo variable is only available in macros. It is replaced by - the actual number of parameters that were given in the macro invocation. - - Example: - - <tscreen><verb> - .macro foo arg1, arg2, arg3 - .if .paramcount <> 3 - .error "Too few parameters for macro foo" - .endif - ... - .endmacro - </verb></tscreen> - - See section <ref id="macros" name="Macros">. - - -<sect1><tt>.TIME</tt><label id=".TIME"><p> - - Reading this pseudo variable will give a constant integer value that - represents the current time in POSIX standard (as seconds since the - Epoch). - - It may be used to encode the time of translation somewhere in the created - code. - - Example: - - <tscreen><verb> - .dword .time ; Place time here - </verb></tscreen> - - -<sect1><tt>.VERSION</tt><label id=".VERSION"><p> - - Reading this pseudo variable will give the assembler version according to - the following formula: - - VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH - - It may be used to encode the assembler version or check the assembler for - special features not available with older versions. - - Example: - - Version 2.11.1 of the assembler will return $2B1 as numerical constant when - reading the pseudo variable <tt/.VERSION/. - - - -<sect>Pseudo functions<label id="pseudo-functions"><p> - -Pseudo functions expect their arguments in parenthesis, and they have a result, -either a string or an expression. - - -<sect1><tt>.BANK</tt><label id=".BANK"><p> - - The <tt/.BANK/ function is used to support systems with banked memory. The - argument is an expression with exactly one segment reference - usually a - label. The function result is the value of the <tt/bank/ attribute assigned - to the run memory area of the segment. Please see the linker documentation - for more information about memory areas and their attributes. - - The value of <tt/.BANK/ can be used to switch memory so that a memory bank - containing specific data is available. - - The <tt/bank/ attribute is a 32 bit integer and so is the result of the - <tt/.BANK/ function. You will have to use <tt><ref id=".LOBYTE" - name=".LOBYTE"></tt> or similar functions to address just part of it. - - Please note that <tt/.BANK/ will always get evaluated in the link stage, so - an expression containing <tt/.BANK/ can never be used where a constant known - result is expected (for example with <tt/.RES/). - - Example: - - <tscreen><verb> - .segment "BANK1" - .proc banked_func_1 - ... - .endproc - - .segment "BANK2" - .proc banked_func_2 - ... - .endproc - - .proc bank_table - .addr banked_func_1 - .byte <.BANK (banked_func_1) - - .addr banked_func_2 - .byte <.BANK (banked_func_2) - .endproc - </verb></tscreen> - - - -<sect1><tt>.BANKBYTE</tt><label id=".BANKBYTE"><p> - - The function returns the bank byte (that is, bits 16-23) of its argument. - It works identical to the '^' operator. - - See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>, - <tt><ref id=".LOBYTE" name=".LOBYTE"></tt> - - -<sect1><tt>.BLANK</tt><label id=".BLANK"><p> - - Builtin function. The function evaluates its argument in braces and yields - "false" if the argument is non blank (there is an argument), and "true" if - there is no argument. The token list that makes up the function argument - may optionally be enclosed in curly braces. This allows the inclusion of - tokens that would otherwise terminate the list (the closing right - parenthesis). The curly braces are not considered part of the list, a list - just consisting of curly braces is considered to be empty. - - As an example, the <tt/.IFBLANK/ statement may be replaced by - - <tscreen><verb> - .if .blank({arg}) - </verb></tscreen> - - - -<sect1><tt>.CONCAT</tt><label id=".CONCAT"><p> - - Builtin string function. The function allows to concatenate a list of string - constants separated by commas. The result is a string constant that is the - concatenation of all arguments. This function is most useful in macros and - when used together with the <tt/.STRING/ builtin function. The function may - be used in any case where a string constant is expected. - - Example: - - <tscreen><verb> - .include .concat ("myheader", ".", "inc") - </verb></tscreen> - - This is the same as the command - - <tscreen><verb> - .include "myheader.inc" - </verb></tscreen> - - -<sect1><tt>.CONST</tt><label id=".CONST"><p> - - Builtin function. The function evaluates its argument in braces and - yields "true" if the argument is a constant expression (that is, an - expression that yields a constant value at assembly time) and "false" - otherwise. As an example, the .IFCONST statement may be replaced by - - <tscreen><verb> - .if .const(a + 3) - </verb></tscreen> - - -<sect1><tt>.HIBYTE</tt><label id=".HIBYTE"><p> - - The function returns the high byte (that is, bits 8-15) of its argument. - It works identical to the '>' operator. - - See: <tt><ref id=".LOBYTE" name=".LOBYTE"></tt>, - <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt> - - -<sect1><tt>.HIWORD</tt><label id=".HIWORD"><p> - - The function returns the high word (that is, bits 16-31) of its argument. - - See: <tt><ref id=".LOWORD" name=".LOWORD"></tt> - - -<sect1><tt>.IDENT</tt><label id=".IDENT"><p> - - The function expects a string as its argument, and converts this argument - into an identifier. If the string starts with the current <tt/<ref - id=".LOCALCHAR" name=".LOCALCHAR">/, it will be converted into a cheap local - identifier, otherwise it will be converted into a normal identifier. - - Example: - - <tscreen><verb> - .macro makelabel arg1, arg2 - .ident (.concat (arg1, arg2)): - .endmacro - - makelabel "foo", "bar" - - .word foobar ; Valid label - </verb></tscreen> - - -<sect1><tt>.LEFT</tt><label id=".LEFT"><p> - - Builtin function. Extracts the left part of a given token list. - - Syntax: - - <tscreen><verb> - .LEFT (<int expr>, <token list>) - </verb></tscreen> - - The first integer expression gives the number of tokens to extract from - the token list. The second argument is the token list itself. The token - list may optionally be enclosed into curly braces. This allows the - inclusion of tokens that would otherwise terminate the list (the closing - right paren in the given case). - - Example: - - To check in a macro if the given argument has a '#' as first token - (immediate addressing mode), use something like this: - - <tscreen><verb> - .macro ldax arg - ... - .if (.match (.left (1, {arg}), #)) - - ; ldax called with immediate operand - ... - - .endif - ... - .endmacro - </verb></tscreen> - - See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT" - name=".RIGHT"></tt> builtin functions. - - -<sect1><tt>.LOBYTE</tt><label id=".LOBYTE"><p> - - The function returns the low byte (that is, bits 0-7) of its argument. - It works identical to the '<' operator. - - See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>, - <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt> - - -<sect1><tt>.LOWORD</tt><label id=".LOWORD"><p> - - The function returns the low word (that is, bits 0-15) of its argument. - - See: <tt><ref id=".HIWORD" name=".HIWORD"></tt> - - -<sect1><tt>.MATCH</tt><label id=".MATCH"><p> - - Builtin function. Matches two token lists against each other. This is - most useful within macros, since macros are not stored as strings, but - as lists of tokens. - - The syntax is - - <tscreen><verb> - .MATCH(<token list #1>, <token list #2>) - </verb></tscreen> - - Both token list may contain arbitrary tokens with the exception of the - terminator token (comma resp. right parenthesis) and - - <itemize> - <item>end-of-line - <item>end-of-file - </itemize> - - The token lists may optionally be enclosed into curly braces. This allows - the inclusion of tokens that would otherwise terminate the list (the closing - right paren in the given case). Often a macro parameter is used for any of - the token lists. - - Please note that the function does only compare tokens, not token - attributes. So any number is equal to any other number, regardless of the - actual value. The same is true for strings. If you need to compare tokens - <em/and/ token attributes, use the <tt><ref id=".XMATCH" - name=".XMATCH"></tt> function. - - Example: - - Assume the macro <tt/ASR/, that will shift right the accumulator by one, - while honoring the sign bit. The builtin processor instructions will allow - an optional "A" for accu addressing for instructions like <tt/ROL/ and - <tt/ROR/. We will use the <tt><ref id=".MATCH" name=".MATCH"></tt> function - to check for this and print and error for invalid calls. - - <tscreen><verb> - .macro asr arg - - .if (.not .blank(arg)) .and (.not .match ({arg}, a)) - .error "Syntax error" - .endif - - cmp #$80 ; Bit 7 into carry - lsr a ; Shift carry into bit 7 - - .endmacro - </verb></tscreen> - - The macro will only accept no arguments, or one argument that must be the - reserved keyword "A". - - See: <tt><ref id=".XMATCH" name=".XMATCH"></tt> - - -<sect1><tt>.MAX</tt><label id=".MAX"><p> - - Builtin function. The result is the larger of two values. - - The syntax is - - <tscreen><verb> - .MAX (<value #1>, <value #2>) - </verb></tscreen> - - Example: - - <tscreen><verb> - ; Reserve space for the larger of two data blocks - savearea: .max (.sizeof (foo), .sizeof (bar)) - </verb></tscreen> - - See: <tt><ref id=".MIN" name=".MIN"></tt> - - -<sect1><tt>.MID</tt><label id=".MID"><p> - - Builtin function. Takes a starting index, a count and a token list as - arguments. Will return part of the token list. - - Syntax: - - <tscreen><verb> - .MID (<int expr>, <int expr>, <token list>) - </verb></tscreen> - - The first integer expression gives the starting token in the list (the first - token has index 0). The second integer expression gives the number of tokens - to extract from the token list. The third argument is the token list itself. - The token list may optionally be enclosed into curly braces. This allows the - inclusion of tokens that would otherwise terminate the list (the closing - right paren in the given case). - - Example: - - To check in a macro if the given argument has a '<tt/#/' as first token - (immediate addressing mode), use something like this: - - <tscreen><verb> - .macro ldax arg - ... - .if (.match (.mid (0, 1, {arg}), #)) - - ; ldax called with immediate operand - ... - - .endif - ... - .endmacro - </verb></tscreen> - - See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT" - name=".RIGHT"></tt> builtin functions. - - -<sect1><tt>.MIN</tt><label id=".MIN"><p> - - Builtin function. The result is the smaller of two values. - - The syntax is - - <tscreen><verb> - .MIN (<value #1>, <value #2>) - </verb></tscreen> - - Example: - - <tscreen><verb> - ; Reserve space for some data, but 256 bytes minimum - savearea: .min (.sizeof (foo), 256) - </verb></tscreen> - - See: <tt><ref id=".MAX" name=".MAX"></tt> - - -<sect1><tt>.REF, .REFERENCED</tt><label id=".REFERENCED"><p> - - Builtin function. The function expects an identifier as argument in braces. - The argument is evaluated, and the function yields "true" if the identifier - is a symbol that has already been referenced somewhere in the source file up - to the current position. Otherwise the function yields false. As an example, - the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by - - <tscreen><verb> - .if .referenced(a) - </verb></tscreen> - - See: <tt><ref id=".DEFINED" name=".DEFINED"></tt> - - -<sect1><tt>.RIGHT</tt><label id=".RIGHT"><p> - - Builtin function. Extracts the right part of a given token list. - - Syntax: - - <tscreen><verb> - .RIGHT (<int expr>, <token list>) - </verb></tscreen> - - The first integer expression gives the number of tokens to extract from the - token list. The second argument is the token list itself. The token list - may optionally be enclosed into curly braces. This allows the inclusion of - tokens that would otherwise terminate the list (the closing right paren in - the given case). - - See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID" - name=".MID"></tt> builtin functions. - - -<sect1><tt>.SIZEOF</tt><label id=".SIZEOF"><p> - - <tt/.SIZEOF/ is a pseudo function that returns the size of its argument. The - argument can be a struct/union, a struct member, a procedure, or a label. In - case of a procedure or label, its size is defined by the amount of data - placed in the segment where the label is relative to. If a line of code - switches segments (for example in a macro) data placed in other segments - does not count for the size. - - Please note that a symbol or scope must exist, before it is used together with - <tt/.SIZEOF/ (this may get relaxed later, but will always be true for scopes). - A scope has preference over a symbol with the same name, so if the last part - of a name represents both, a scope and a symbol, the scope is chosen over the - symbol. - - After the following code: - - <tscreen><verb> - .struct Point ; Struct size = 4 - xcoord .word - ycoord .word - .endstruct - - P: .tag Point ; Declare a point - @P: .tag Point ; Declare another point - - .code - .proc Code - nop - .proc Inner - nop - .endproc - nop - .endproc - - .proc Data - .data ; Segment switch!!! - .res 4 - .endproc - </verb></tscreen> - - <descrip> - <tag><tt/.sizeof(Point)/</tag> - will have the value 4, because this is the size of struct <tt/Point/. - - <tag><tt/.sizeof(Point::xcoord)/</tag> - will have the value 2, because this is the size of the member <tt/xcoord/ - in struct <tt/Point/. - - <tag><tt/.sizeof(P)/</tag> - will have the value 4, this is the size of the data declared on the same - source line as the label <tt/P/, which is in the same segment that <tt/P/ - is relative to. - - <tag><tt/.sizeof(@P)/</tag> - will have the value 4, see above. The example demonstrates that <tt/.SIZEOF/ - does also work for cheap local symbols. - - <tag><tt/.sizeof(Code)/</tag> - will have the value 3, since this is amount of data emitted into the code - segment, the segment that was active when <tt/Code/ was entered. Note that - this value includes the amount of data emitted in child scopes (in this - case <tt/Code::Inner/). - - <tag><tt/.sizeof(Code::Inner)/</tag> - will have the value 1 as expected. - - <tag><tt/.sizeof(Data)/</tag> - will have the value 0. Data is emitted within the scope <tt/Data/, but since - the segment is switched after entry, this data is emitted into another - segment. - </descrip> - - -<sect1><tt>.STRAT</tt><label id=".STRAT"><p> - - Builtin function. The function accepts a string and an index as - arguments and returns the value of the character at the given position - as an integer value. The index is zero based. - - Example: - - <tscreen><verb> - .macro M Arg - ; Check if the argument string starts with '#' - .if (.strat (Arg, 0) = '#') - ... - .endif - .endmacro - </verb></tscreen> - - -<sect1><tt>.SPRINTF</tt><label id=".SPRINTF"><p> - - Builtin function. It expects a format string as first argument. The number - and type of the following arguments depend on the format string. The format - string is similar to the one of the C <tt/printf/ function. Missing things - are: Length modifiers, variable width. - - The result of the function is a string. - - Example: - - <tscreen><verb> - num = 3 - - ; Generate an identifier: - .ident (.sprintf ("%s%03d", "label", num)): - </verb></tscreen> - - -<sect1><tt>.STRING</tt><label id=".STRING"><p> - - Builtin function. The function accepts an argument in braces and converts - this argument into a string constant. The argument may be an identifier, or - a constant numeric value. - - Since you can use a string in the first place, the use of the function may - not be obvious. However, it is useful in macros, or more complex setups. - - Example: - - <tscreen><verb> - ; Emulate other assemblers: - .macro section name - .segment .string(name) - .endmacro - </verb></tscreen> - - -<sect1><tt>.STRLEN</tt><label id=".STRLEN"><p> - - Builtin function. The function accepts a string argument in braces and - evaluates to the length of the string. - - Example: - - The following macro encodes a string as a pascal style string with - a leading length byte. - - <tscreen><verb> - .macro PString Arg - .byte .strlen(Arg), Arg - .endmacro - </verb></tscreen> - - -<sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p> - - Builtin function. The function accepts a token list in braces. The function - result is the number of tokens given as argument. The token list may - optionally be enclosed into curly braces which are not considered part of - the list and not counted. Enclosement in curly braces allows the inclusion - of tokens that would otherwise terminate the list (the closing right paren - in the given case). - - Example: - - The <tt/ldax/ macro accepts the '#' token to denote immediate addressing (as - with the normal 6502 instructions). To translate it into two separate 8 bit - load instructions, the '#' token has to get stripped from the argument: - - <tscreen><verb> - .macro ldax arg - .if (.match (.mid (0, 1, {arg}), #)) - ; ldax called with immediate operand - lda #<(.right (.tcount ({arg})-1, {arg})) - ldx #>(.right (.tcount ({arg})-1, {arg})) - .else - ... - .endif - .endmacro - </verb></tscreen> - - -<sect1><tt>.XMATCH</tt><label id=".XMATCH"><p> - - Builtin function. Matches two token lists against each other. This is - most useful within macros, since macros are not stored as strings, but - as lists of tokens. - - The syntax is - - <tscreen><verb> - .XMATCH(<token list #1>, <token list #2>) - </verb></tscreen> - - Both token list may contain arbitrary tokens with the exception of the - terminator token (comma resp. right parenthesis) and - - <itemize> - <item>end-of-line - <item>end-of-file - </itemize> - - The token lists may optionally be enclosed into curly braces. This allows - the inclusion of tokens that would otherwise terminate the list (the closing - right paren in the given case). Often a macro parameter is used for any of - the token lists. - - The function compares tokens <em/and/ token values. If you need a function - that just compares the type of tokens, have a look at the <tt><ref - id=".MATCH" name=".MATCH"></tt> function. - - See: <tt><ref id=".MATCH" name=".MATCH"></tt> - - - -<sect>Control commands<label id="control-commands"><p> - -Here's a list of all control commands and a description, what they do: - - -<sect1><tt>.A16</tt><label id=".A16"><p> - - Valid only in 65816 mode. Switch the accumulator to 16 bit. - - Note: This command will not emit any code, it will tell the assembler to - create 16 bit operands for immediate accumulator addressing mode. - - See also: <tt><ref id=".SMART" name=".SMART"></tt> - - -<sect1><tt>.A8</tt><label id=".A8"><p> - - Valid only in 65816 mode. Switch the accumulator to 8 bit. - - Note: This command will not emit any code, it will tell the assembler to - create 8 bit operands for immediate accu addressing mode. - - See also: <tt><ref id=".SMART" name=".SMART"></tt> - - -<sect1><tt>.ADDR</tt><label id=".ADDR"><p> - - Define word sized data. In 6502 mode, this is an alias for <tt/.WORD/ and - may be used for better readability if the data words are address values. In - 65816 mode, the address is forced to be 16 bit wide to fit into the current - segment. See also <tt><ref id=".FARADDR" name=".FARADDR"></tt>. The command - must be followed by a sequence of (not necessarily constant) expressions. - - Example: - - <tscreen><verb> - .addr $0D00, $AF13, _Clear - </verb></tscreen> - - See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD" - name=".WORD"></tt> - - -<sect1><tt>.ALIGN</tt><label id=".ALIGN"><p> - - Align data to a given boundary. The command expects a constant integer - argument in the range 1 ... 65536, plus an optional second argument - in byte range. If there is a second argument, it is used as fill value, - otherwise the value defined in the linker configuration file is used - (the default for this value is zero). - - <tt/.ALIGN/ will insert fill bytes, and the number of fill bytes depend of - the final address of the segment. <tt/.ALIGN/ cannot insert a variable - number of bytes, since that would break address calculations within the - module. So each <tt/.ALIGN/ expects the segment to be aligned to a multiple - of the alignment, because that allows the number of fill bytes to be - calculated in advance by the assembler. You are therefore required to - specify a matching alignment for the segment in the linker config. The - linker will output a warning if the alignment of the segment is less than - what is necessary to have a correct alignment in the object file. - - Example: - - <tscreen><verb> - .align 256 - </verb></tscreen> - - Some unexpected behaviour might occur if there are multiple <tt/.ALIGN/ - commands with different arguments. To allow the assembler to calculate the - number of fill bytes in advance, the alignment of the segment must be a - multiple of each of the alignment factors. This may result in unexpectedly - large alignments for the segment within the module. - - Example: - - <tscreen><verb> - .align 15 - .byte 15 - .align 18 - .byte 18 - </verb></tscreen> - - For the assembler to be able to align correctly, the segment must be aligned - to the least common multiple of 15 and 18 which is 90. The assembler will - calculate this automatically and will mark the segment with this value. - - Unfortunately, the combined alignment may get rather large without the user - knowing about it, wasting space in the final executable. If we add another - alignment to the example above - - <tscreen><verb> - .align 15 - .byte 15 - .align 18 - .byte 18 - .align 251 - .byte 0 - </verb></tscreen> - - the assembler will force a segment alignment to the least common multiple of - 15, 18 and 251 - which is 22590. To protect the user against errors, the - assembler will issue a warning when the combined alignment exceeds 256. The - command line option <tt><ref id="option--large-alignment" - name="--large-alignment"></tt> will disable this warning. - - Please note that with alignments that are a power of two (which were the - only alignments possible in older versions of the assembler), the problem is - less severe, because the least common multiple of powers to the same base is - always the larger one. - - - -<sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p> - - Define a string with a trailing zero. - - Example: - - <tscreen><verb> - Msg: .asciiz "Hello world" - </verb></tscreen> - - This will put the string "Hello world" followed by a binary zero into - the current segment. There may be more strings separated by commas, but - the binary zero is only appended once (after the last one). - - -<sect1><tt>.ASSERT</tt><label id=".ASSERT"><p> - - Add an assertion. The command is followed by an expression, an action - specifier, and an optional message that is output in case the assertion - fails. If no message was given, the string "Assertion failed" is used. The - action specifier may be one of <tt/warning/, <tt/error/, <tt/ldwarning/ or - <tt/lderror/. In the former two cases, the assertion is evaluated by the - assembler if possible, and in any case, it's also passed to the linker in - the object file (if one is generated). The linker will then evaluate the - expression when segment placement has been done. - - Example: - - <tscreen><verb> - .assert * = $8000, error, "Code not at $8000" - </verb></tscreen> - - The example assertion will check that the current location is at $8000, - when the output file is written, and abort with an error if this is not - the case. More complex expressions are possible. The action specifier - <tt/warning/ outputs a warning, while the <tt/error/ specifier outputs - an error message. In the latter case, generation of the output file is - suppressed in both the assembler and linker. - - -<sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p> - - Is followed by a plus or a minus character. When switched on (using a - +), undefined symbols are automatically marked as import instead of - giving errors. When switched off (which is the default so this does not - make much sense), this does not happen and an error message is - displayed. The state of the autoimport flag is evaluated when the - complete source was translated, before outputting actual code, so it is - <em/not/ possible to switch this feature on or off for separate sections - of code. The last setting is used for all symbols. - - You should probably not use this switch because it delays error - messages about undefined symbols until the link stage. The cc65 - compiler (which is supposed to produce correct assembler code in all - circumstances, something which is not true for most assembler - programmers) will insert this command to avoid importing each and every - routine from the runtime library. - - Example: - - <tscreen><verb> - .autoimport + ; Switch on auto import - </verb></tscreen> - -<sect1><tt>.BANKBYTES</tt><label id=".BANKBYTES"><p> - - Define byte sized data by extracting only the bank byte (that is, bits 16-23) from - each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with - the operator '^' prepended to each expression in its list. - - Example: - - <tscreen><verb> - .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 - - TableLookupLo: .lobytes MyTable - TableLookupHi: .hibytes MyTable - TableLookupBank: .bankbytes MyTable - </verb></tscreen> - - which is equivalent to - - <tscreen><verb> - TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 - TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 - TableLookupBank: .byte ^TableItem0, ^TableItem1, ^TableItem2, ^TableItem3 - </verb></tscreen> - - See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, - <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>, - <tt><ref id=".LOBYTES" name=".LOBYTES"></tt> - - -<sect1><tt>.BSS</tt><label id=".BSS"><p> - - Switch to the BSS segment. The name of the BSS segment is always "BSS", - so this is a shortcut for - - <tscreen><verb> - .segment "BSS" - </verb></tscreen> - - See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. - - -<sect1><tt>.BYT, .BYTE</tt><label id=".BYTE"><p> - - Define byte sized data. Must be followed by a sequence of (byte ranged) - expressions or strings. - - Example: - - <tscreen><verb> - .byte "Hello " - .byt "world", $0D, $00 - </verb></tscreen> - - -<sect1><tt>.CASE</tt><label id=".CASE"><p> - - Switch on or off case sensitivity on identifiers. The default is off - (that is, identifiers are case sensitive), but may be changed by the - -i switch on the command line. - The command must be followed by a '+' or '-' character to switch the - option on or off respectively. - - Example: - - <tscreen><verb> - .case - ; Identifiers are not case sensitive - </verb></tscreen> - - -<sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p> - - Apply a custom mapping for characters. The command is followed by two - numbers. The first one is the index of the source character (range 1..255), - the second one is the mapping (range 0..255). The mapping applies to all - character and string constants when they generate output, and overrides a - mapping table specified with the <tt><ref id="option-t" name="-t"></tt> - command line switch. - - Example: - - <tscreen><verb> - .charmap $41, $61 ; Map 'A' to 'a' - </verb></tscreen> - - -<sect1><tt>.CODE</tt><label id=".CODE"><p> - - Switch to the CODE segment. The name of the CODE segment is always - "CODE", so this is a shortcut for - - <tscreen><verb> - .segment "CODE" - </verb></tscreen> - - See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. - - -<sect1><tt>.CONDES</tt><label id=".CONDES"><p> - - Export a symbol and mark it in a special way. The linker is able to build - tables of all such symbols. This may be used to automatically create a list - of functions needed to initialize linked library modules. - - Note: The linker has a feature to build a table of marked routines, but it - is your code that must call these routines, so just declaring a symbol with - <tt/.CONDES/ does nothing by itself. - - All symbols are exported as an absolute (16 bit) symbol. You don't need to - use an additional <tt><ref id=".EXPORT" name=".EXPORT"></tt> statement, this - is implied by <tt/.CONDES/. - - <tt/.CONDES/ is followed by the type, which may be <tt/constructor/, - <tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as - specifying <tt/constructor/ and 1 is equal to specifying <tt/destructor/). - The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref - id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" - name=".INTERRUPTOR"></tt> commands are actually shortcuts for <tt/.CONDES/ - with a type of <tt/constructor/ resp. <tt/destructor/ or <tt/interruptor/. - - After the type, an optional priority may be specified. Higher numeric values - mean higher priority. If no priority is given, the default priority of 7 is - used. Be careful when assigning priorities to your own module constructors - so they won't interfere with the ones in the cc65 library. - - Example: - - <tscreen><verb> - .condes ModuleInit, constructor - .condes ModInit, 0, 16 - </verb></tscreen> - - See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref - id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" - name=".INTERRUPTOR"></tt> commands and the separate section <ref id="condes" - name="Module constructors/destructors"> explaining the feature in more - detail. - - -<sect1><tt>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p> - - Export a symbol and mark it as a module constructor. This may be used - together with the linker to build a table of constructor subroutines that - are called by the startup code. - - Note: The linker has a feature to build a table of marked routines, but it - is your code that must call these routines, so just declaring a symbol as - constructor does nothing by itself. - - A constructor is always exported as an absolute (16 bit) symbol. You don't - need to use an additional <tt/.export/ statement, this is implied by - <tt/.constructor/. It may have an optional priority that is separated by a - comma. Higher numeric values mean a higher priority. If no priority is - given, the default priority of 7 is used. Be careful when assigning - priorities to your own module constructors so they won't interfere with the - ones in the cc65 library. - - Example: - - <tscreen><verb> - .constructor ModuleInit - .constructor ModInit, 16 - </verb></tscreen> - - See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref - id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section - <ref id="condes" name="Module constructors/destructors"> explaining the - feature in more detail. - - -<sect1><tt>.DATA</tt><label id=".DATA"><p> - - Switch to the DATA segment. The name of the DATA segment is always - "DATA", so this is a shortcut for - - <tscreen><verb> - .segment "DATA" - </verb></tscreen> - - See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. - - -<sect1><tt>.DBYT</tt><label id=".DBYT"><p> - - Define word sized data with the hi and lo bytes swapped (use <tt/.WORD/ to - create word sized data in native 65XX format). Must be followed by a - sequence of (word ranged) expressions. - - Example: - - <tscreen><verb> - .dbyt $1234, $4512 - </verb></tscreen> - - This will emit the bytes - - <tscreen><verb> - $12 $34 $45 $12 - </verb></tscreen> - - into the current segment in that order. - - -<sect1><tt>.DEBUGINFO</tt><label id=".DEBUGINFO"><p> - - Switch on or off debug info generation. The default is off (that is, - the object file will not contain debug infos), but may be changed by the - -g switch on the command line. - The command must be followed by a '+' or '-' character to switch the - option on or off respectively. - - Example: - - <tscreen><verb> - .debuginfo + ; Generate debug info - </verb></tscreen> - - -<sect1><tt>.DEFINE</tt><label id=".DEFINE"><p> - - Start a define style macro definition. The command is followed by an - identifier (the macro name) and optionally by a list of formal arguments - in braces. - - Please note that <tt/.DEFINE/ shares most disadvantages with its C - counterpart, so the general advice is, <bf/NOT/ do use <tt/.DEFINE/ if you - don't have to. - - See also the <tt><ref id=".UNDEFINE" name=".UNDEFINE"></tt> command and - section <ref id="macros" name="Macros">. - - -<sect1><tt>.DELMAC, .DELMACRO</tt><label id=".DELMACRO"><p> - - Delete a classic macro (defined with <tt><ref id=".MACRO" - name=".MACRO"></tt>) . The command is followed by the name of an - existing macro. Its definition will be deleted together with the name. - If necessary, another macro with this name may be defined later. - - See: <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, - <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>, - <tt><ref id=".MACRO" name=".MACRO"></tt> - - See also section <ref id="macros" name="Macros">. - - -<sect1><tt>.DEF, .DEFINED</tt><label id=".DEFINED"><p> - - Builtin function. The function expects an identifier as argument in braces. - The argument is evaluated, and the function yields "true" if the identifier - is a symbol that is already defined somewhere in the source file up to the - current position. Otherwise the function yields false. As an example, the - <tt><ref id=".IFDEF" name=".IFDEF"></tt> statement may be replaced by - - <tscreen><verb> - .if .defined(a) - </verb></tscreen> - - -<sect1><tt>.DESTRUCTOR</tt><label id=".DESTRUCTOR"><p> - - Export a symbol and mark it as a module destructor. This may be used - together with the linker to build a table of destructor subroutines that - are called by the startup code. - - Note: The linker has a feature to build a table of marked routines, but it - is your code that must call these routines, so just declaring a symbol as - constructor does nothing by itself. - - A destructor is always exported as an absolute (16 bit) symbol. You don't - need to use an additional <tt/.export/ statement, this is implied by - <tt/.destructor/. It may have an optional priority that is separated by a - comma. Higher numerical values mean a higher priority. If no priority is - given, the default priority of 7 is used. Be careful when assigning - priorities to your own module destructors so they won't interfere with the - ones in the cc65 library. - - Example: - - <tscreen><verb> - .destructor ModuleDone - .destructor ModDone, 16 - </verb></tscreen> - - See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref - id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> commands and the separate - section <ref id="condes" name="Module constructors/destructors"> explaining - the feature in more detail. - - -<sect1><tt>.DWORD</tt><label id=".DWORD"><p> - - Define dword sized data (4 bytes) Must be followed by a sequence of - expressions. - - Example: - - <tscreen><verb> - .dword $12344512, $12FA489 - </verb></tscreen> - - -<sect1><tt>.ELSE</tt><label id=".ELSE"><p> - - Conditional assembly: Reverse the current condition. - - -<sect1><tt>.ELSEIF</tt><label id=".ELSEIF"><p> - - Conditional assembly: Reverse current condition and test a new one. - - -<sect1><tt>.END</tt><label id=".END"><p> - - Forced end of assembly. Assembly stops at this point, even if the command - is read from an include file. - - -<sect1><tt>.ENDENUM</tt><label id=".ENDENUM"><p> - - End a <tt><ref id=".ENUM" name=".ENUM"></tt> declaration. - - -<sect1><tt>.ENDIF</tt><label id=".ENDIF"><p> - - Conditional assembly: Close a <tt><ref id=".IF" name=".IF..."></tt> or - <tt><ref id=".ELSE" name=".ELSE"></tt> branch. - - -<sect1><tt>.ENDMAC, .ENDMACRO</tt><label id=".ENDMACRO"><p> - - Marks the end of a macro definition. - - See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, - <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>, - <tt><ref id=".MACRO" name=".MACRO"></tt> - - See also section <ref id="macros" name="Macros">. - - -<sect1><tt>.ENDPROC</tt><label id=".ENDPROC"><p> - - End of local lexical level (see <tt><ref id=".PROC" name=".PROC"></tt>). - - -<sect1><tt>.ENDREP, .ENDREPEAT</tt><label id=".ENDREPEAT"><p> - - End a <tt><ref id=".REPEAT" name=".REPEAT"></tt> block. - - -<sect1><tt>.ENDSCOPE</tt><label id=".ENDSCOPE"><p> - - End of local lexical level (see <tt/<ref id=".SCOPE" name=".SCOPE">/). - - -<sect1><tt>.ENDSTRUCT</tt><label id=".ENDSTRUCT"><p> - - Ends a struct definition. See the <tt/<ref id=".STRUCT" name=".STRUCT">/ - command and the separate section named <ref id="structs" name=""Structs - and unions"">. - - -<sect1><tt>.ENDUNION</tt><label id=".ENDUNION"><p> - - Ends a union definition. See the <tt/<ref id=".UNION" name=".UNION">/ - command and the separate section named <ref id="structs" name=""Structs - and unions"">. - - -<sect1><tt>.ENUM</tt><label id=".ENUM"><p> - - Start an enumeration. This directive is very similar to the C <tt/enum/ - keyword. If a name is given, a new scope is created for the enumeration, - otherwise the enumeration members are placed in the enclosing scope. - - In the enumeration body, symbols are declared. The first symbol has a value - of zero, and each following symbol will get the value of the preceding plus - one. This behaviour may be overridden by an explicit assignment. Two symbols - may have the same value. - - Example: - - <tscreen><verb> - .enum errorcodes - no_error - file_error - parse_error - .endenum - </verb></tscreen> - - Above example will create a new scope named <tt/errorcodes/ with three - symbols in it that get the values 0, 1 and 2 respectively. Another way - to write this would have been: - - <tscreen><verb> - .scope errorcodes - no_error = 0 - file_error = 1 - parse_error = 2 - .endscope - </verb></tscreen> - - Please note that explicit scoping must be used to access the identifiers: - - <tscreen><verb> - .word errorcodes::no_error - </verb></tscreen> - - A more complex example: - - <tscreen><verb> - .enum - EUNKNOWN = -1 - EOK - EFILE - EBUSY - EAGAIN - EWOULDBLOCK = EAGAIN - .endenum - </verb></tscreen> - - In this example, the enumeration does not have a name, which means that the - members will be visible in the enclosing scope and can be used in this scope - without explicit scoping. The first member (<tt/EUNKNOWN/) has the value -1. - The value for the following members is incremented by one, so <tt/EOK/ would - be zero and so on. <tt/EWOULDBLOCK/ is an alias for <tt/EGAIN/, so it has an - override for the value using an already defined symbol. - - -<sect1><tt>.ERROR</tt><label id=".ERROR"><p> - - Force an assembly error. The assembler will output an error message - preceded by "User error". Assembly is continued but no object file will - generated. - - This command may be used to check for initial conditions that must be - set before assembling a source file. - - Example: - - <tscreen><verb> - .if foo = 1 - ... - .elseif bar = 1 - ... - .else - .error "Must define foo or bar!" - .endif - </verb></tscreen> - - See also: <tt><ref id=".FATAL" name=".FATAL"></tt>, - <tt><ref id=".OUT" name=".OUT"></tt>, - <tt><ref id=".WARNING" name=".WARNING"></tt> - - -<sect1><tt>.EXITMAC, .EXITMACRO</tt><label id=".EXITMACRO"><p> - - Abort a macro expansion immediately. This command is often useful in - recursive macros. - - See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, - <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, - <tt><ref id=".MACRO" name=".MACRO"></tt> - - See also section <ref id="macros" name="Macros">. - - -<sect1><tt>.EXPORT</tt><label id=".EXPORT"><p> - - Make symbols accessible from other modules. Must be followed by a comma - separated list of symbols to export, with each one optionally followed by an - address specification and (also optional) an assignment. Using an additional - assignment in the export statement allows to define and export a symbol in - one statement. The default is to export the symbol with the address size it - actually has. The assembler will issue a warning, if the symbol is exported - with an address size smaller than the actual address size. - - Examples: - - <tscreen><verb> - .export foo - .export bar: far - .export foobar: far = foo * bar - .export baz := foobar, zap: far = baz - bar - </verb></tscreen> - - As with constant definitions, using <tt/:=/ instead of <tt/=/ marks the - symbols as a label. - - See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt> - - -<sect1><tt>.EXPORTZP</tt><label id=".EXPORTZP"><p> - - Make symbols accessible from other modules. Must be followed by a comma - separated list of symbols to export. The exported symbols are explicitly - marked as zero page symbols. An assignment may be included in the - <tt/.EXPORTZP/ statement. This allows to define and export a symbol in one - statement. - - Examples: - - <tscreen><verb> - .exportzp foo, bar - .exportzp baz := $02 - </verb></tscreen> - - See: <tt><ref id=".EXPORT" name=".EXPORT"></tt> - - -<sect1><tt>.FARADDR</tt><label id=".FARADDR"><p> - - Define far (24 bit) address data. The command must be followed by a - sequence of (not necessarily constant) expressions. - - Example: - - <tscreen><verb> - .faraddr DrawCircle, DrawRectangle, DrawHexagon - </verb></tscreen> - - See: <tt><ref id=".ADDR" name=".ADDR"></tt> - - -<sect1><tt>.FATAL</tt><label id=".FATAL"><p> - - Force an assembly error and terminate assembly. The assembler will output an - error message preceded by "User error" and will terminate assembly - immediately. - - This command may be used to check for initial conditions that must be - set before assembling a source file. - - Example: - - <tscreen><verb> - .if foo = 1 - ... - .elseif bar = 1 - ... - .else - .fatal "Must define foo or bar!" - .endif - </verb></tscreen> - - See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, - <tt><ref id=".OUT" name=".OUT"></tt>, - <tt><ref id=".WARNING" name=".WARNING"></tt> - - -<sect1><tt>.FEATURE</tt><label id=".FEATURE"><p> - - This directive may be used to enable one or more compatibility features - of the assembler. While the use of <tt/.FEATURE/ should be avoided when - possible, it may be useful when porting sources written for other - assemblers. There is no way to switch a feature off, once you have - enabled it, so using - - <tscreen><verb> - .FEATURE xxx - </verb></tscreen> - - will enable the feature until end of assembly is reached. - - The following features are available: - - <descrip> - - <tag><tt>at_in_identifiers</tt><label id="at_in_identifiers"></tag> - - Accept the at character (`@') as a valid character in identifiers. The - at character is not allowed to start an identifier, even with this - feature enabled. - - <tag><tt>c_comments</tt><label id="c_comments"></tag> - - Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right - comment terminators. Note that C comments may not be nested. There's also a - pitfall when using C like comments: All statements must be terminated by - "end-of-line". Using C like comments, it is possible to hide the newline, - which results in error messages. See the following non working example: - - <tscreen><verb> - lda #$00 /* This comment hides the newline -*/ sta $82 - </verb></tscreen> - - <tag><tt>dollar_in_identifiers</tt><label id="dollar_in_identifiers"></tag> - - Accept the dollar sign (`$') as a valid character in identifiers. The - dollar character is not allowed to start an identifier, even with this - feature enabled. - - <tag><tt>dollar_is_pc</tt><label id="dollar_is_pc"></tag> - - The dollar sign may be used as an alias for the star (`*'), which - gives the value of the current PC in expressions. - Note: Assignment to the pseudo variable is not allowed. - - <tag><tt>force_range</tt><label id="force_range"></tag> - - Force expressions into their valid range for immediate addressing and - storage operators like <tt><ref id=".BYTE" name=".BYTE"></tt> and - <tt><ref id=".WORD" name=".WORD"></tt>. Be very careful with this one, - since it will completely disable error checks. - - <tag><tt>labels_without_colons</tt><label id="labels_without_colons"></tag> - - Allow labels without a trailing colon. These labels are only accepted, - if they start at the beginning of a line (no leading white space). - - <tag><tt>leading_dot_in_identifiers</tt><label id="leading_dot_in_identifiers"></tag> - - Accept the dot (`.') as the first character of an identifier. This may be - used for example to create macro names that start with a dot emulating - control directives of other assemblers. Note however, that none of the - reserved keywords built into the assembler, that starts with a dot, may be - overridden. When using this feature, you may also get into trouble if - later versions of the assembler define new keywords starting with a dot. - - <tag><tt>loose_char_term</tt><label id="loose_char_term"></tag> - - Accept single quotes as well as double quotes as terminators for char - constants. - - <tag><tt>loose_string_term</tt><label id="loose_string_term"></tag> - - Accept single quotes as well as double quotes as terminators for string - constants. - - <tag><tt>missing_char_term</tt><label id="missing_char_term"></tag> - - Accept single quoted character constants where the terminating quote is - missing. - <tscreen><verb> - lda #'a - </verb></tscreen> - <bf/Note:/ This does not work in conjunction with <tt/.FEATURE - loose_string_term/, since in this case the input would be ambiguous. - - <tag><tt>org_per_seg</tt><label id="org_per_seg"></tag> - - This feature makes relocatable/absolute mode local to the current segment. - Using <tt><ref id=".ORG" name=".ORG"></tt> when <tt/org_per_seg/ is in - effect will only enable absolute mode for the current segment. Dito for - <tt><ref id=".RELOC" name=".RELOC"></tt>. - - <tag><tt>pc_assignment</tt><label id="pc_assignment"></tag> - - Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/ - is enabled). Such an assignment is handled identical to the <tt><ref - id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just - removing the lines with the assignments may also be an option when porting - code written for older assemblers). - - <tag><tt>ubiquitous_idents</tt><label id="ubiquitous_idents"></tag> - - Allow the use of instructions names as names for macros and symbols. This - makes it possible to "overload" instructions by defining a macro with the - same name. This does also make it possible to introduce hard to find errors - in your code, so be careful! - - <tag><tt>underline_in_numbers</tt><label id="underline_in_numbers"></tag> - - Allow underlines within numeric constants. These may be used for grouping - the digits of numbers for easier reading. - Example: - <tscreen><verb> - .feature underline_in_numbers - .word %1100001110100101 - .word %1100_0011_1010_0101 ; Identical but easier to read - </verb></tscreen> - - </descrip> - - It is also possible to specify features on the command line using the - <tt><ref id="option--feature" name="--feature"></tt> command line option. - This is useful when translating sources written for older assemblers, when - you don't want to change the source code. - - As an example, to translate sources written for Andre Fachats xa65 - assembler, the features - - <verb> - labels_without_colons, pc_assignment, loose_char_term - </verb> - - may be helpful. They do not make ca65 completely compatible, so you may not - be able to translate the sources without changes, even when enabling these - features. However, I have found several sources that translate without - problems when enabling these features on the command line. - - -<sect1><tt>.FILEOPT, .FOPT</tt><label id=".FOPT"><p> - - Insert an option string into the object file. There are two forms of - this command, one specifies the option by a keyword, the second - specifies it as a number. Since usage of the second one needs knowledge - of the internal encoding, its use is not recommended and I will only - describe the first form here. - - The command is followed by one of the keywords - - <tscreen><verb> - author - comment - compiler - </verb></tscreen> - - a comma and a string. The option is written into the object file - together with the string value. This is currently unidirectional and - there is no way to actually use these options once they are in the - object file. - - Examples: - - <tscreen><verb> - .fileopt comment, "Code stolen from my brother" - .fileopt compiler, "BASIC 2.0" - .fopt author, "J. R. User" - </verb></tscreen> - - -<sect1><tt>.FORCEIMPORT</tt><label id=".FORCEIMPORT"><p> - - Import an absolute symbol from another module. The command is followed by a - comma separated list of symbols to import. The command is similar to <tt> - <ref id=".IMPORT" name=".IMPORT"></tt>, but the import reference is always - written to the generated object file, even if the symbol is never referenced - (<tt><ref id=".IMPORT" name=".IMPORT"></tt> will not generate import - references for unused symbols). - - Example: - - <tscreen><verb> - .forceimport needthisone, needthistoo - </verb></tscreen> - - See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> - - -<sect1><tt>.GLOBAL</tt><label id=".GLOBAL"><p> - - Declare symbols as global. Must be followed by a comma separated list of - symbols to declare. Symbols from the list, that are defined somewhere in the - source, are exported, all others are imported. Additional <tt><ref - id=".IMPORT" name=".IMPORT"></tt> or <tt><ref id=".EXPORT" - name=".EXPORT"></tt> commands for the same symbol are allowed. - - Example: - - <tscreen><verb> - .global foo, bar - </verb></tscreen> - - -<sect1><tt>.GLOBALZP</tt><label id=".GLOBALZP"><p> - - Declare symbols as global. Must be followed by a comma separated list of - symbols to declare. Symbols from the list, that are defined somewhere in the - source, are exported, all others are imported. Additional <tt><ref - id=".IMPORTZP" name=".IMPORTZP"></tt> or <tt><ref id=".EXPORTZP" - name=".EXPORTZP"></tt> commands for the same symbol are allowed. The symbols - in the list are explicitly marked as zero page symbols. - - Example: - - <tscreen><verb> - .globalzp foo, bar - </verb></tscreen> - -<sect1><tt>.HIBYTES</tt><label id=".HIBYTES"><p> - - Define byte sized data by extracting only the high byte (that is, bits 8-15) from - each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with - the operator '>' prepended to each expression in its list. - - Example: - - <tscreen><verb> - .lobytes $1234, $2345, $3456, $4567 - .hibytes $fedc, $edcb, $dcba, $cba9 - </verb></tscreen> - - which is equivalent to - - <tscreen><verb> - .byte $34, $45, $56, $67 - .byte $fe, $ed, $dc, $cb - </verb></tscreen> - - Example: - - <tscreen><verb> - .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 - - TableLookupLo: .lobytes MyTable - TableLookupHi: .hibytes MyTable - </verb></tscreen> - - which is equivalent to - - <tscreen><verb> - TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 - TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 - </verb></tscreen> - - See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, - <tt><ref id=".LOBYTES" name=".LOBYTES"></tt>, - <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt> - - -<sect1><tt>.I16</tt><label id=".I16"><p> - - Valid only in 65816 mode. Switch the index registers to 16 bit. - - Note: This command will not emit any code, it will tell the assembler to - create 16 bit operands for immediate operands. - - See also the <tt><ref id=".I8" name=".I8"></tt> and <tt><ref id=".SMART" - name=".SMART"></tt> commands. - - -<sect1><tt>.I8</tt><label id=".I8"><p> - - Valid only in 65816 mode. Switch the index registers to 8 bit. - - Note: This command will not emit any code, it will tell the assembler to - create 8 bit operands for immediate operands. - - See also the <tt><ref id=".I16" name=".I16"></tt> and <tt><ref id=".SMART" - name=".SMART"></tt> commands. - - -<sect1><tt>.IF</tt><label id=".IF"><p> - - Conditional assembly: Evaluate an expression and switch assembler output - on or off depending on the expression. The expression must be a constant - expression, that is, all operands must be defined. - - A expression value of zero evaluates to FALSE, any other value evaluates - to TRUE. - - -<sect1><tt>.IFBLANK</tt><label id=".IFBLANK"><p> - - Conditional assembly: Check if there are any remaining tokens in this line, - and evaluate to FALSE if this is the case, and to TRUE otherwise. If the - condition is not true, further lines are not assembled until an <tt><ref - id=".ELSE" name=".ESLE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or - <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. - - This command is often used to check if a macro parameter was given. Since an - empty macro parameter will evaluate to nothing, the condition will evaluate - to TRUE if an empty parameter was given. - - Example: - - <tscreen><verb> - .macro arg1, arg2 - .ifblank arg2 - lda #arg1 - .else - lda #arg2 - .endif - .endmacro - </verb></tscreen> - - See also: <tt><ref id=".BLANK" name=".BLANK"></tt> - - -<sect1><tt>.IFCONST</tt><label id=".IFCONST"><p> - - Conditional assembly: Evaluate an expression and switch assembler output - on or off depending on the constness of the expression. - - A const expression evaluates to to TRUE, a non const expression (one - containing an imported or currently undefined symbol) evaluates to - FALSE. - - See also: <tt><ref id=".CONST" name=".CONST"></tt> - - -<sect1><tt>.IFDEF</tt><label id=".IFDEF"><p> - - Conditional assembly: Check if a symbol is defined. Must be followed by - a symbol name. The condition is true if the the given symbol is already - defined, and false otherwise. - - See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt> - - -<sect1><tt>.IFNBLANK</tt><label id=".IFNBLANK"><p> - - Conditional assembly: Check if there are any remaining tokens in this line, - and evaluate to TRUE if this is the case, and to FALSE otherwise. If the - condition is not true, further lines are not assembled until an <tt><ref - id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or - <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. - - This command is often used to check if a macro parameter was given. - Since an empty macro parameter will evaluate to nothing, the condition - will evaluate to FALSE if an empty parameter was given. - - Example: - - <tscreen><verb> - .macro arg1, arg2 - lda #arg1 - .ifnblank arg2 - lda #arg2 - .endif - .endmacro - </verb></tscreen> - - See also: <tt><ref id=".BLANK" name=".BLANK"></tt> - - -<sect1><tt>.IFNDEF</tt><label id=".IFNDEF"><p> - - Conditional assembly: Check if a symbol is defined. Must be followed by - a symbol name. The condition is true if the the given symbol is not - defined, and false otherwise. - - See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt> - - -<sect1><tt>.IFNREF</tt><label id=".IFNREF"><p> - - Conditional assembly: Check if a symbol is referenced. Must be followed - by a symbol name. The condition is true if if the the given symbol was - not referenced before, and false otherwise. - - See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> - - -<sect1><tt>.IFP02</tt><label id=".IFP02"><p> - - Conditional assembly: Check if the assembler is currently in 6502 mode - (see <tt><ref id=".P02" name=".P02"></tt> command). - - -<sect1><tt>.IFP816</tt><label id=".IFP816"><p> - - Conditional assembly: Check if the assembler is currently in 65816 mode - (see <tt><ref id=".P816" name=".P816"></tt> command). - - -<sect1><tt>.IFPC02</tt><label id=".IFPC02"><p> - - Conditional assembly: Check if the assembler is currently in 65C02 mode - (see <tt><ref id=".PC02" name=".PC02"></tt> command). - - -<sect1><tt>.IFPSC02</tt><label id=".IFPSC02"><p> - - Conditional assembly: Check if the assembler is currently in 65SC02 mode - (see <tt><ref id=".PSC02" name=".PSC02"></tt> command). - - -<sect1><tt>.IFREF</tt><label id=".IFREF"><p> - - Conditional assembly: Check if a symbol is referenced. Must be followed - by a symbol name. The condition is true if if the the given symbol was - referenced before, and false otherwise. - - This command may be used to build subroutine libraries in include files - (you may use separate object modules for this purpose too). - - Example: - - <tscreen><verb> - .ifref ToHex ; If someone used this subroutine - ToHex: tay ; Define subroutine - lda HexTab,y - rts - .endif - </verb></tscreen> - - See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> - - -<sect1><tt>.IMPORT</tt><label id=".IMPORT"><p> - - Import a symbol from another module. The command is followed by a comma - separated list of symbols to import, with each one optionally followed by - an address specification. - - Example: - - <tscreen><verb> - .import foo - .import bar: zeropage - </verb></tscreen> - - See: <tt><ref id=".IMPORTZP" name=".IMPORTZP"></tt> - - -<sect1><tt>.IMPORTZP</tt><label id=".IMPORTZP"><p> - - Import a symbol from another module. The command is followed by a comma - separated list of symbols to import. The symbols are explicitly imported - as zero page symbols (that is, symbols with values in byte range). - - Example: - - <tscreen><verb> - .importzp foo, bar - </verb></tscreen> - - See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> - - -<sect1><tt>.INCBIN</tt><label id=".INCBIN"><p> - - Include a file as binary data. The command expects a string argument - that is the name of a file to include literally in the current segment. - In addition to that, a start offset and a size value may be specified, - separated by commas. If no size is specified, all of the file from the - start offset to end-of-file is used. If no start position is specified - either, zero is assumed (which means that the whole file is inserted). - - Example: - - <tscreen><verb> - ; Include whole file - .incbin "sprites.dat" - - ; Include file starting at offset 256 - .incbin "music.dat", $100 - - ; Read 100 bytes starting at offset 200 - .incbin "graphics.dat", 200, 100 - </verb></tscreen> - - -<sect1><tt>.INCLUDE</tt><label id=".INCLUDE"><p> - - Include another file. Include files may be nested up to a depth of 16. - - Example: - - <tscreen><verb> - .include "subs.inc" - </verb></tscreen> - - -<sect1><tt>.INTERRUPTOR</tt><label id=".INTERRUPTOR"><p> - - Export a symbol and mark it as an interruptor. This may be used together - with the linker to build a table of interruptor subroutines that are called - in an interrupt. - - Note: The linker has a feature to build a table of marked routines, but it - is your code that must call these routines, so just declaring a symbol as - interruptor does nothing by itself. - - An interruptor is always exported as an absolute (16 bit) symbol. You don't - need to use an additional <tt/.export/ statement, this is implied by - <tt/.interruptor/. It may have an optional priority that is separated by a - comma. Higher numeric values mean a higher priority. If no priority is - given, the default priority of 7 is used. Be careful when assigning - priorities to your own module constructors so they won't interfere with the - ones in the cc65 library. - - Example: - - <tscreen><verb> - .interruptor IrqHandler - .interruptor Handler, 16 - </verb></tscreen> - - See the <tt><ref id=".CONDES" name=".CONDES"></tt> command and the separate - section <ref id="condes" name="Module constructors/destructors"> explaining - the feature in more detail. - - -<sect1><tt>.LINECONT</tt><label id=".LINECONT"><p> - - Switch on or off line continuations using the backslash character - before a newline. The option is off by default. - Note: Line continuations do not work in a comment. A backslash at the - end of a comment is treated as part of the comment and does not trigger - line continuation. - The command must be followed by a '+' or '-' character to switch the - option on or off respectively. - - Example: - - <tscreen><verb> - .linecont + ; Allow line continuations - - lda \ - #$20 ; This is legal now - </verb></tscreen> - - -<sect1><tt>.LIST</tt><label id=".LIST"><p> - - Enable output to the listing. The command must be followed by a boolean - switch ("on", "off", "+" or "-") and will enable or disable listing - output. - The option has no effect if the listing is not enabled by the command line - switch -l. If -l is used, an internal counter is set to 1. Lines are output - to the listing file, if the counter is greater than zero, and suppressed if - the counter is zero. Each use of <tt/.LIST/ will increment or decrement the - counter. - - Example: - - <tscreen><verb> - .list on ; Enable listing output - </verb></tscreen> - - -<sect1><tt>.LISTBYTES</tt><label id=".LISTBYTES"><p> - - Set, how many bytes are shown in the listing for one source line. The - default is 12, so the listing will show only the first 12 bytes for any - source line that generates more than 12 bytes of code or data. - The directive needs an argument, which is either "unlimited", or an - integer constant in the range 4..255. - - Examples: - - <tscreen><verb> - .listbytes unlimited ; List all bytes - .listbytes 12 ; List the first 12 bytes - .incbin "data.bin" ; Include large binary file - </verb></tscreen> - - -<sect1><tt>.LOBYTES</tt><label id=".LOBYTES"><p> - - Define byte sized data by extracting only the low byte (that is, bits 0-7) from - each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with - the operator '<' prepended to each expression in its list. - - Example: - - <tscreen><verb> - .lobytes $1234, $2345, $3456, $4567 - .hibytes $fedc, $edcb, $dcba, $cba9 - </verb></tscreen> - - which is equivalent to - - <tscreen><verb> - .byte $34, $45, $56, $67 - .byte $fe, $ed, $dc, $cb - </verb></tscreen> - - Example: - - <tscreen><verb> - .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 - - TableLookupLo: .lobytes MyTable - TableLookupHi: .hibytes MyTable - </verb></tscreen> - - which is equivalent to - - <tscreen><verb> - TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 - TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 - </verb></tscreen> - - See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, - <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>, - <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt> - - -<sect1><tt>.LOCAL</tt><label id=".LOCAL"><p> - - This command may only be used inside a macro definition. It declares a - list of identifiers as local to the macro expansion. - - A problem when using macros are labels: Since they don't change their name, - you get a "duplicate symbol" error if the macro is expanded the second time. - Labels declared with <tt><ref id=".LOCAL" name=".LOCAL"></tt> have their - name mapped to an internal unique name (<tt/___ABCD__/) with each macro - invocation. - - Some other assemblers start a new lexical block inside a macro expansion. - This has some drawbacks however, since that will not allow <em/any/ symbol - to be visible outside a macro, a feature that is sometimes useful. The - <tt><ref id=".LOCAL" name=".LOCAL"></tt> command is in my eyes a better way - to address the problem. - - You get an error when using <tt><ref id=".LOCAL" name=".LOCAL"></tt> outside - a macro. - - -<sect1><tt>.LOCALCHAR</tt><label id=".LOCALCHAR"><p> - - Defines the character that start "cheap" local labels. You may use one - of '@' and '?' as start character. The default is '@'. - - Cheap local labels are labels that are visible only between two non - cheap labels. This way you can reuse identifiers like "<tt/loop/" without - using explicit lexical nesting. - - Example: - - <tscreen><verb> - .localchar '?' - - Clear: lda #$00 ; Global label - ?Loop: sta Mem,y ; Local label - dey - bne ?Loop ; Ok - rts - Sub: ... ; New global label - bne ?Loop ; ERROR: Unknown identifier! - </verb></tscreen> - - -<sect1><tt>.MACPACK</tt><label id=".MACPACK"><p> - - Insert a predefined macro package. The command is followed by an - identifier specifying the macro package to insert. Available macro - packages are: - - <tscreen><verb> - atari Defines the scrcode macro. - cbm Defines the scrcode macro. - cpu Defines constants for the .CPU variable. - generic Defines generic macros like add and sub. - longbranch Defines conditional long jump macros. - </verb></tscreen> - - Including a macro package twice, or including a macro package that - redefines already existing macros will lead to an error. - - Example: - - <tscreen><verb> - .macpack longbranch ; Include macro package - - cmp #$20 ; Set condition codes - jne Label ; Jump long on condition - </verb></tscreen> - - Macro packages are explained in more detail in section <ref - id="macropackages" name="Macro packages">. - - -<sect1><tt>.MAC, .MACRO</tt><label id=".MACRO"><p> - - Start a classic macro definition. The command is followed by an identifier - (the macro name) and optionally by a comma separated list of identifiers - that are macro parameters. A macro definition is terminated by <tt><ref - id=".ENDMACRO" name=".ENDMACRO"></tt>. - - Example: - - <tscreen><verb> - .macro ldax arg ; Define macro ldax - lda arg - ldx arg+1 - </verb></tscreen> - - See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, - <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, - <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt> - - See also section <ref id="macros" name="Macros">. - - -<sect1><tt>.ORG</tt><label id=".ORG"><p> - - Start a section of absolute code. The command is followed by a constant - expression that gives the new PC counter location for which the code is - assembled. Use <tt><ref id=".RELOC" name=".RELOC"></tt> to switch back to - relocatable code. - - By default, absolute/relocatable mode is global (valid even when switching - segments). Using <tt>.FEATURE <ref id="org_per_seg" name="org_per_seg"></tt> - it can be made segment local. - - Please note that you <em/do not need/ <tt/.ORG/ in most cases. Placing - code at a specific address is the job of the linker, not the assembler, so - there is usually no reason to assemble code to a specific address. - - Example: - - <tscreen><verb> - .org $7FF ; Emit code starting at $7FF - </verb></tscreen> - - -<sect1><tt>.OUT</tt><label id=".OUT"><p> - - Output a string to the console without producing an error. This command - is similar to <tt/.ERROR/, however, it does not force an assembler error - that prevents the creation of an object file. - - Example: - - <tscreen><verb> - .out "This code was written by the codebuster(tm)" - </verb></tscreen> - - See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, - <tt><ref id=".FATAL" name=".FATAL"></tt>, - <tt><ref id=".WARNING" name=".WARNING"></tt> - - -<sect1><tt>.P02</tt><label id=".P02"><p> - - Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816 - instructions. This is the default if not overridden by the - <tt><ref id="option--cpu" name="--cpu"></tt> command line option. - - See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02" - name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> - - -<sect1><tt>.P816</tt><label id=".P816"><p> - - Enable the 65816 instruction set. This is a superset of the 65SC02 and - 6502 instruction sets. - - See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" - name=".PSC02"></tt> and <tt><ref id=".PC02" name=".PC02"></tt> - - -<sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p> - - Set the page length for the listing. Must be followed by an integer - constant. The value may be "unlimited", or in the range 32 to 127. The - statement has no effect if no listing is generated. The default value is -1 - (unlimited) but may be overridden by the <tt/--pagelength/ command line - option. Beware: Since ca65 is a one pass assembler, the listing is generated - after assembly is complete, you cannot use multiple line lengths with one - source. Instead, the value set with the last <tt/.PAGELENGTH/ is used. - - Examples: - - <tscreen><verb> - .pagelength 66 ; Use 66 lines per listing page - - .pagelength unlimited ; Unlimited page length - </verb></tscreen> - - -<sect1><tt>.PC02</tt><label id=".PC02"><p> - - Enable the 65C02 instructions set. This instruction set includes all - 6502 and 65SC02 instructions. - - See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" - name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> - - -<sect1><tt>.POPCPU</tt><label id=".POPCPU"><p> - - Pop the last CPU setting from the stack, and activate it. - - This command will switch back to the CPU that was last pushed onto the CPU - stack using the <tt><ref id=".PUSHCPU" name=".PUSHCPU"></tt> command, and - remove this entry from the stack. - - The assembler will print an error message if the CPU stack is empty when - this command is issued. - - See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".PUSHCPU" - name=".PUSHCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt> - - -<sect1><tt>.POPSEG</tt><label id=".POPSEG"><p> - - Pop the last pushed segment from the stack, and set it. - - This command will switch back to the segment that was last pushed onto the - segment stack using the <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt> - command, and remove this entry from the stack. - - The assembler will print an error message if the segment stack is empty - when this command is issued. - - See: <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt> - - -<sect1><tt>.PROC</tt><label id=".PROC"><p> - - Start a nested lexical level with the given name and adds a symbol with this - name to the enclosing scope. All new symbols from now on are in the local - lexical level and are accessible from outside only via <ref id="scopesyntax" - name="explicit scope specification">. Symbols defined outside this local - level may be accessed as long as their names are not used for new symbols - inside the level. Symbols names in other lexical levels do not clash, so you - may use the same names for identifiers. The lexical level ends when the - <tt><ref id=".ENDPROC" name=".ENDPROC"></tt> command is read. Lexical levels - may be nested up to a depth of 16 (this is an artificial limit to protect - against errors in the source). - - Note: Macro names are always in the global level and in a separate name - space. There is no special reason for this, it's just that I've never - had any need for local macro definitions. - - Example: - - <tscreen><verb> - .proc Clear ; Define Clear subroutine, start new level - lda #$00 - L1: sta Mem,y ; L1 is local and does not cause a - ; duplicate symbol error if used in other - ; places - dey - bne L1 ; Reference local symbol - rts - .endproc ; Leave lexical level - </verb></tscreen> - - See: <tt/<ref id=".ENDPROC" name=".ENDPROC">/ and <tt/<ref id=".SCOPE" - name=".SCOPE">/ - - -<sect1><tt>.PSC02</tt><label id=".PSC02"><p> - - Enable the 65SC02 instructions set. This instruction set includes all - 6502 instructions. - - See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02" - name=".PC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> - - -<sect1><tt>.PUSHCPU</tt><label id=".PUSHCPU"><p> - - Push the currently active CPU onto a stack. The stack has a size of 8 - entries. - - <tt/.PUSHCPU/ allows together with <tt><ref id=".POPCPU" - name=".POPCPU"></tt> to switch to another CPU and to restore the old CPU - later, without knowledge of the current CPU setting. - - The assembler will print an error message if the CPU stack is already full, - when this command is issued. - - See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".POPCPU" - name=".POPCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt> - - -<sect1><tt>.PUSHSEG</tt><label id=".PUSHSEG"><p> - - Push the currently active segment onto a stack. The entries on the stack - include the name of the segment and the segment type. The stack has a size - of 16 entries. - - <tt/.PUSHSEG/ allows together with <tt><ref id=".POPSEG" name=".POPSEG"></tt> - to switch to another segment and to restore the old segment later, without - even knowing the name and type of the current segment. - - The assembler will print an error message if the segment stack is already - full, when this command is issued. - - See: <tt><ref id=".POPSEG" name=".POPSEG"></tt> - - -<sect1><tt>.RELOC</tt><label id=".RELOC"><p> - - Switch back to relocatable mode. See the <tt><ref id=".ORG" - name=".ORG"></tt> command. - - -<sect1><tt>.REPEAT</tt><label id=".REPEAT"><p> - - Repeat all commands between <tt/.REPEAT/ and <tt><ref id=".ENDREPEAT" - name=".ENDREPEAT"></tt> constant number of times. The command is followed by - a constant expression that tells how many times the commands in the body - should get repeated. Optionally, a comma and an identifier may be specified. - If this identifier is found in the body of the repeat statement, it is - replaced by the current repeat count (starting with zero for the first time - the body is repeated). - - <tt/.REPEAT/ statements may be nested. If you use the same repeat count - identifier for a nested <tt/.REPEAT/ statement, the one from the inner - level will be used, not the one from the outer level. - - Example: - - The following macro will emit a string that is "encrypted" in that all - characters of the string are XORed by the value $55. - - <tscreen><verb> - .macro Crypt Arg - .repeat .strlen(Arg), I - .byte .strat(Arg, I) ^ $55 - .endrep - .endmacro - </verb></tscreen> - - See: <tt><ref id=".ENDREPEAT" name=".ENDREPEAT"></tt> - - -<sect1><tt>.RES</tt><label id=".RES"><p> - - Reserve storage. The command is followed by one or two constant - expressions. The first one is mandatory and defines, how many bytes of - storage should be defined. The second, optional expression must by a - constant byte value that will be used as value of the data. If there - is no fill value given, the linker will use the value defined in the - linker configuration file (default: zero). - - Example: - - <tscreen><verb> - ; Reserve 12 bytes of memory with value $AA - .res 12, $AA - </verb></tscreen> - - -<sect1><tt>.RODATA</tt><label id=".RODATA"><p> - - Switch to the RODATA segment. The name of the RODATA segment is always - "RODATA", so this is a shortcut for - - <tscreen><verb> - .segment "RODATA" - </verb></tscreen> - - The RODATA segment is a segment that is used by the compiler for - readonly data like string constants. - - See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. - - -<sect1><tt>.SCOPE</tt><label id=".SCOPE"><p> - - Start a nested lexical level with the given name. All new symbols from now - on are in the local lexical level and are accessible from outside only via - <ref id="scopesyntax" name="explicit scope specification">. Symbols defined - outside this local level may be accessed as long as their names are not used - for new symbols inside the level. Symbols names in other lexical levels do - not clash, so you may use the same names for identifiers. The lexical level - ends when the <tt><ref id=".ENDSCOPE" name=".ENDSCOPE"></tt> command is - read. Lexical levels may be nested up to a depth of 16 (this is an - artificial limit to protect against errors in the source). - - Note: Macro names are always in the global level and in a separate name - space. There is no special reason for this, it's just that I've never - had any need for local macro definitions. - - Example: - - <tscreen><verb> - .scope Error ; Start new scope named Error - None = 0 ; No error - File = 1 ; File error - Parse = 2 ; Parse error - .endscope ; Close lexical level - - ... - lda #Error::File ; Use symbol from scope Error - </verb></tscreen> - - See: <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/ and <tt/<ref id=".PROC" - name=".PROC">/ - - -<sect1><tt>.SEGMENT</tt><label id=".SEGMENT"><p> - - Switch to another segment. Code and data is always emitted into a - segment, that is, a named section of data. The default segment is - "CODE". There may be up to 254 different segments per object file - (and up to 65534 per executable). There are shortcut commands for - the most common segments ("CODE", "DATA" and "BSS"). - - The command is followed by a string containing the segment name (there are - some constraints for the name - as a rule of thumb use only those segment - names that would also be valid identifiers). There may also be an optional - address size separated by a colon. See the section covering <tt/<ref - id="address-sizes" name="address sizes">/ for more information. - - The default address size for a segment depends on the memory model specified - on the command line. The default is "absolute", which means that you don't - have to use an address size modifier in most cases. - - "absolute" means that the is a segment with 16 bit (absolute) addressing. - That is, the segment will reside somewhere in core memory outside the zero - page. "zeropage" (8 bit) means that the segment will be placed in the zero - page and direct (short) addressing is possible for data in this segment. - - Beware: Only labels in a segment with the zeropage attribute are marked - as reachable by short addressing. The `*' (PC counter) operator will - work as in other segments and will create absolute variable values. - - Please note that a segment cannot have two different address sizes. A - segment specified as zeropage cannot be declared as being absolute later. - - Examples: - - <tscreen><verb> - .segment "ROM2" ; Switch to ROM2 segment - .segment "ZP2": zeropage ; New direct segment - .segment "ZP2" ; Ok, will use last attribute - .segment "ZP2": absolute ; Error, redecl mismatch - </verb></tscreen> - - See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE" - name=".CODE"></tt>, <tt><ref id=".DATA" name=".DATA"></tt> and <tt><ref - id=".RODATA" name=".RODATA"></tt> - - -<sect1><tt>.SET</tt><label id=".SET"><p> - - <tt/.SET/ is used to assign a value to a variable. See <ref id="variables" - name="Numeric variables"> for a full description. - - -<sect1><tt>.SETCPU</tt><label id=".SETCPU"><p> - - Switch the CPU instruction set. The command is followed by a string that - specifies the CPU. Possible values are those that can also be supplied to - the <tt><ref id="option--cpu" name="--cpu"></tt> command line option, - namely: 6502, 6502X, 65SC02, 65C02, 65816, sunplus and HuC6280. Please - note that support for the sunplus CPU is not available in the freeware - version, because the instruction set of the sunplus CPU is "proprietary - and confidential". - - See: <tt><ref id=".CPU" name=".CPU"></tt>, - <tt><ref id=".IFP02" name=".IFP02"></tt>, - <tt><ref id=".IFP816" name=".IFP816"></tt>, - <tt><ref id=".IFPC02" name=".IFPC02"></tt>, - <tt><ref id=".IFPSC02" name=".IFPSC02"></tt>, - <tt><ref id=".P02" name=".P02"></tt>, - <tt><ref id=".P816" name=".P816"></tt>, - <tt><ref id=".PC02" name=".PC02"></tt>, - <tt><ref id=".PSC02" name=".PSC02"></tt> - - -<sect1><tt>.SMART</tt><label id=".SMART"><p> - - Switch on or off smart mode. The command must be followed by a '+' or '-' - character to switch the option on or off respectively. The default is off - (that is, the assembler doesn't try to be smart), but this default may be - changed by the -s switch on the command line. - - In smart mode the assembler will do the following: - - <itemize> - <item>Track usage of the <tt/REP/ and <tt/SEP/ instructions in 65816 mode - and update the operand sizes accordingly. If the operand of such an - instruction cannot be evaluated by the assembler (for example, because - the operand is an imported symbol), a warning is issued. Beware: Since - the assembler cannot trace the execution flow this may lead to false - results in some cases. If in doubt, use the <tt/.Inn/ and <tt/.Ann/ - instructions to tell the assembler about the current settings. - <item>In 65816 mode, replace a <tt/RTS/ instruction by <tt/RTL/ if it is - used within a procedure declared as <tt/far/, or if the procedure has - no explicit address specification, but it is <tt/far/ because of the - memory model used. - </itemize> - - Example: - - <tscreen><verb> - .smart ; Be smart - .smart - ; Stop being smart - </verb></tscreen> - - See: <tt><ref id=".A16" name=".A16"></tt>, - <tt><ref id=".A8" name=".A8"></tt>, - <tt><ref id=".I16" name=".I16"></tt>, - <tt><ref id=".I8" name=".I8"></tt> - - -<sect1><tt>.STRUCT</tt><label id=".STRUCT"><p> - - Starts a struct definition. Structs are covered in a separate section named - <ref id="structs" name=""Structs and unions"">. - - See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>, - <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>, - <tt><ref id=".UNION" name=".UNION"></tt> - - -<sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p> - - Enable the SunPlus instructions set. This command will not work in the - freeware version of the assembler, because the instruction set is - "proprietary and confidential". - - See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" - name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, and - <tt><ref id=".P816" name=".P816"></tt> - - -<sect1><tt>.TAG</tt><label id=".TAG"><p> - - Allocate space for a struct or union. - - Example: - - <tscreen><verb> - .struct Point - xcoord .word - ycoord .word - .endstruct - - .bss - .tag Point ; Allocate 4 bytes - </verb></tscreen> - - -<sect1><tt>.UNDEF, .UNDEFINE</tt><label id=".UNDEFINE"><p> - - Delete a define style macro definition. The command is followed by an - identifier which specifies the name of the macro to delete. Macro - replacement is switched of when reading the token following the command - (otherwise the macro name would be replaced by its replacement list). - - See also the <tt><ref id=".DEFINE" name=".DEFINE"></tt> command and - section <ref id="macros" name="Macros">. - - -<sect1><tt>.UNION</tt><label id=".UNION"><p> - - Starts a union definition. Unions are covered in a separate section named - <ref id="structs" name=""Structs and unions"">. - - See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>, - <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>, - <tt><ref id=".STRUCT" name=".STRUCT"></tt> - - -<sect1><tt>.WARNING</tt><label id=".WARNING"><p> - - Force an assembly warning. The assembler will output a warning message - preceded by "User warning". This warning will always be output, even if - other warnings are disabled with the <tt><ref id="option-W" name="-W0"></tt> - command line option. - - This command may be used to output possible problems when assembling - the source file. - - Example: - - <tscreen><verb> - .macro jne target - .local L1 - .ifndef target - .warning "Forward jump in jne, cannot optimize!" - beq L1 - jmp target - L1: - .else - ... - .endif - .endmacro - </verb></tscreen> - - See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, - <tt><ref id=".FATAL" name=".FATAL"></tt>, - <tt><ref id=".OUT" name=".OUT"></tt> - - -<sect1><tt>.WORD</tt><label id=".WORD"><p> - - Define word sized data. Must be followed by a sequence of (word ranged, - but not necessarily constant) expressions. - - Example: - - <tscreen><verb> - .word $0D00, $AF13, _Clear - </verb></tscreen> - - -<sect1><tt>.ZEROPAGE</tt><label id=".ZEROPAGE"><p> - - Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment. - The name of the ZEROPAGE segment is always "ZEROPAGE", so this is a - shortcut for - - <tscreen><verb> - .segment "ZEROPAGE", zeropage - </verb></tscreen> - - Because of the "zeropage" attribute, labels declared in this segment are - addressed using direct addressing mode if possible. You <em/must/ instruct - the linker to place this segment somewhere in the address range 0..$FF - otherwise you will get errors. - - See: <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> - - - -<sect>Macros<label id="macros"><p> - - -<sect1>Introduction<p> - -Macros may be thought of as "parametrized super instructions". Macros are -sequences of tokens that have a name. If that name is used in the source -file, the macro is "expanded", that is, it is replaced by the tokens that -were specified when the macro was defined. - - -<sect1>Macros without parameters<p> - -In its simplest form, a macro does not have parameters. Here's an -example: - -<tscreen><verb> - .macro asr ; Arithmetic shift right - cmp #$80 ; Put bit 7 into carry - ror ; Rotate right with carry - .endmacro -</verb></tscreen> - -The macro above consists of two real instructions, that are inserted into -the code, whenever the macro is expanded. Macro expansion is simply done -by using the name, like this: - -<tscreen><verb> - lda $2010 - asr - sta $2010 -</verb></tscreen> - - -<sect1>Parametrized macros<p> - -When using macro parameters, macros can be even more useful: - -<tscreen><verb> - .macro inc16 addr - clc - lda addr - adc #$01 - sta addr - lda addr+1 - adc #$00 - sta addr+1 - .endmacro -</verb></tscreen> - -When calling the macro, you may give a parameter, and each occurrence of -the name "addr" in the macro definition will be replaced by the given -parameter. So - -<tscreen><verb> - inc16 $1000 -</verb></tscreen> - -will be expanded to - -<tscreen><verb> - clc - lda $1000 - adc #$01 - sta $1000 - lda $1000+1 - adc #$00 - sta $1000+1 -</verb></tscreen> - -A macro may have more than one parameter, in this case, the parameters -are separated by commas. You are free to give less parameters than the -macro actually takes in the definition. You may also leave intermediate -parameters empty. Empty parameters are replaced by empty space (that is, -they are removed when the macro is expanded). If you have a look at our -macro definition above, you will see, that replacing the "addr" parameter -by nothing will lead to wrong code in most lines. To help you, writing -macros with a variable parameter list, there are some control commands: - -<tt><ref id=".IFBLANK" name=".IFBLANK"></tt> tests the rest of the line and -returns true, if there are any tokens on the remainder of the line. Since -empty parameters are replaced by nothing, this may be used to test if a given -parameter is empty. <tt><ref id=".IFNBLANK" name=".IFNBLANK"></tt> tests the -opposite. - -Look at this example: - -<tscreen><verb> - .macro ldaxy a, x, y - .ifnblank a - lda #a - .endif - .ifnblank x - ldx #x - .endif - .ifnblank y - ldy #y - .endif - .endmacro -</verb></tscreen> - -This macro may be called as follows: - -<tscreen><verb> - ldaxy 1, 2, 3 ; Load all three registers - - ldaxy 1, , 3 ; Load only a and y - - ldaxy , , 3 ; Load y only -</verb></tscreen> - -There's another helper command for determining, which macro parameters are -valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt> This command is -replaced by the parameter count given, <em/including/ intermediate empty macro -parameters: - -<tscreen><verb> - ldaxy 1 ; .PARAMCOUNT = 1 - ldaxy 1,,3 ; .PARAMCOUNT = 3 - ldaxy 1,2 ; .PARAMCOUNT = 2 - ldaxy 1, ; .PARAMCOUNT = 2 - ldaxy 1,2,3 ; .PARAMCOUNT = 3 -</verb></tscreen> - -Macro parameters may optionally be enclosed into curly braces. This allows the -inclusion of tokens that would otherwise terminate the parameter (the comma in -case of a macro parameter). - -<tscreen><verb> - .macro foo arg1, arg2 - ... - .endmacro - - foo ($00,x) ; Two parameters passed - foo {($00,x)} ; One parameter passed -</verb></tscreen> - -In the first case, the macro is called with two parameters: '<tt/($00/' -and 'x)'. The comma is not passed to the macro, since it is part of the -calling sequence, not the parameters. - -In the second case, '($00,x)' is passed to the macro, this time -including the comma. - - -<sect1>Detecting parameter types<p> - -Sometimes it is nice to write a macro that acts differently depending on the -type of the argument supplied. An example would be a macro that loads a 16 bit -value from either an immediate operand, or from memory. The <tt/<ref -id=".MATCH" name=".MATCH">/ and <tt/<ref id=".XMATCH" name=".XMATCH">/ -functions will allow you to do exactly this: - -<tscreen><verb> - .macro ldax arg - .if (.match (.left (1, {arg}), #)) - ; immediate mode - lda #<(.right (.tcount ({arg})-1, {arg})) - ldx #>(.right (.tcount ({arg})-1, {arg})) - .else - ; assume absolute or zero page - lda arg - ldx 1+(arg) - .endif - .endmacro -</verb></tscreen> - -Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to -check if its argument begins with a hash mark. If so, two immediate loads are -emitted, Otherwise a load from an absolute zero page memory location is -assumed. Please note how the curly braces are used to enclose parameters to -pseudo functions handling token lists. This is necessary, because the token -lists may include commas or parens, which would be treated by the assembler -as end-of-list. - -The macro can be used as - -<tscreen><verb> - foo: .word $5678 - ... - ldax #$1234 ; X=$12, A=$34 - ... - ldax foo ; X=$56, A=$78 -</verb></tscreen> - - -<sect1>Recursive macros<p> - -Macros may be used recursively: - -<tscreen><verb> - .macro push r1, r2, r3 - lda r1 - pha - .if .paramcount > 1 - push r2, r3 - .endif - .endmacro -</verb></tscreen> - -There's also a special macro to help writing recursive macros: <tt><ref -id=".EXITMACRO" name=".EXITMACRO"></tt> This command will stop macro expansion -immediately: - -<tscreen><verb> - .macro push r1, r2, r3, r4, r5, r6, r7 - .ifblank r1 - ; First parameter is empty - .exitmacro - .else - lda r1 - pha - .endif - push r2, r3, r4, r5, r6, r7 - .endmacro -</verb></tscreen> - -When expanding this macro, the expansion will push all given parameters -until an empty one is encountered. The macro may be called like this: - -<tscreen><verb> - push $20, $21, $32 ; Push 3 ZP locations - push $21 ; Push one ZP location -</verb></tscreen> - - -<sect1>Local symbols inside macros<p> - -Now, with recursive macros, <tt><ref id=".IFBLANK" name=".IFBLANK"></tt> and -<tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>, what else do you need? -Have a look at the inc16 macro above. Here is it again: - -<tscreen><verb> - .macro inc16 addr - clc - lda addr - adc #$01 - sta addr - lda addr+1 - adc #$00 - sta addr+1 - .endmacro -</verb></tscreen> - -If you have a closer look at the code, you will notice, that it could be -written more efficiently, like this: - -<tscreen><verb> - .macro inc16 addr - inc addr - bne Skip - inc addr+1 - Skip: - .endmacro -</verb></tscreen> - -But imagine what happens, if you use this macro twice? Since the label "Skip" -has the same name both times, you get a "duplicate symbol" error. Without a -way to circumvent this problem, macros are not as useful, as they could be. -One possible solution is the command <tt><ref id=".LOCAL" name=".LOCAL"></tt>. -It declares one or more symbols as local to the macro expansion. The names of -local variables are replaced by a unique name in each separate macro -expansion. So we can solve the problem above by using <tt/.LOCAL/: - -<tscreen><verb> - .macro inc16 addr - .local Skip ; Make Skip a local symbol - inc addr - bne Skip - inc addr+1 - Skip: ; Not visible outside - .endmacro -</verb></tscreen> - -Another solution is of course to start a new lexical block inside the macro -that hides any labels: - -<tscreen><verb> - .macro inc16 addr - .proc - inc addr - bne Skip - inc addr+1 - Skip: - .endproc - .endmacro -</verb></tscreen> - - -<sect1>C style macros<p> - -Starting with version 2.5 of the assembler, there is a second macro type -available: C style macros using the <tt/.DEFINE/ directive. These macros are -similar to the classic macro type described above, but behaviour is sometimes -different: - -<itemize> - -<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> may not - span more than a line. You may use line continuation (see <tt><ref - id=".LINECONT" name=".LINECONT"></tt>) to spread the definition over - more than one line for increased readability, but the macro itself - may not contain an end-of-line token. - -<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> share - the name space with classic macros, but they are detected and replaced - at the scanner level. While classic macros may be used in every place, - where a mnemonic or other directive is allowed, <tt><ref id=".DEFINE" - name=".DEFINE"></tt> style macros are allowed anywhere in a line. So - they are more versatile in some situations. - -<item> <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may take - parameters. While classic macros may have empty parameters, this is - not true for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros. - For this macro type, the number of actual parameters must match - exactly the number of formal parameters. - - To make this possible, formal parameters are enclosed in braces when - defining the macro. If there are no parameters, the empty braces may - be omitted. - -<item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not - contain end-of-line tokens, there are things that cannot be done. They - may not contain several processor instructions for example. So, while - some things may be done with both macro types, each type has special - usages. The types complement each other. - -</itemize> - -Let's look at a few examples to make the advantages and disadvantages -clear. - -To emulate assemblers that use "<tt/EQU/" instead of "<tt/=/" you may use the -following <tt/.DEFINE/: - -<tscreen><verb> - .define EQU = - - foo EQU $1234 ; This is accepted now -</verb></tscreen> - -You may use the directive to define string constants used elsewhere: - -<tscreen><verb> - ; Define the version number - .define VERSION "12.3a" - - ; ... and use it - .asciiz VERSION -</verb></tscreen> - -Macros with parameters may also be useful: - -<tscreen><verb> - .define DEBUG(message) .out message - - DEBUG "Assembling include file #3" -</verb></tscreen> - -Note that, while formal parameters have to be placed in braces, this is -not true for the actual parameters. Beware: Since the assembler cannot -detect the end of one parameter, only the first token is used. If you -don't like that, use classic macros instead: - -<tscreen><verb> - .macro DEBUG message - .out message - .endmacro -</verb></tscreen> - -(This is an example where a problem can be solved with both macro types). - - -<sect1>Characters in macros<p> - -When using the <ref id="option-t" name="-t"> option, characters are translated -into the target character set of the specific machine. However, this happens -as late as possible. This means that strings are translated if they are part -of a <tt><ref id=".BYTE" name=".BYTE"></tt> or <tt><ref id=".ASCIIZ" -name=".ASCIIZ"></tt> command. Characters are translated as soon as they are -used as part of an expression. - -This behaviour is very intuitive outside of macros but may be confusing when -doing more complex macros. If you compare characters against numeric values, -be sure to take the translation into account. - - -<sect1>Deleting macros<p> - -Macros can be deleted. This will not work if the macro that should be deleted -is currently expanded as in the following non working example: - -<tscreen><verb> - .macro notworking - .delmacro notworking - .endmacro - - notworking ; Will not work -</verb></tscreen> - -The commands to delete classic and define style macros differ. Classic macros -can be deleted by use of <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, while -for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros, <tt><ref -id=".UNDEFINE" name=".UNDEFINE"></tt> must be used. Example: - -<tscreen><verb> - .define value 1 - .macro mac - .byte 2 - .endmacro - - .byte value ; Emit one byte with value 1 - mac ; Emit another byte with value 2 - - .undefine value - .delmacro mac - - .byte value ; Error: Unknown identifier - mac ; Error: Missing ":" -</verb></tscreen> - -A separate command for <tt>.DEFINE</tt> style macros was necessary, because -the name of such a macro is replaced by its replacement list on a very low -level. To get the actual name, macro replacement has to be switched off when -reading the argument to <tt>.UNDEFINE</tt>. This does also mean that the -argument to <tt>.UNDEFINE</tt> is not allowed to come from another -<tt>.DEFINE</tt>. All this is not necessary for classic macros, so having two -different commands increases flexibility. - - -<sect>Macro packages<label id="macropackages"><p> - -Using the <tt><ref id=".MACPACK" name=".MACPACK"></tt> directive, predefined -macro packages may be included with just one command. Available macro packages -are: - - -<sect1><tt>.MACPACK generic</tt><p> - -This macro package defines macros that are useful in almost any program. -Currently defined macros are: - -<tscreen><verb> - .macro add Arg - clc - adc Arg - .endmacro - - .macro sub Arg - sec - sbc Arg - .endmacro - - .macro bge Arg - bcs Arg - .endmacro - - .macro blt Arg - bcc Arg - .endmacro - - .macro bgt Arg - .local L - beq L - bcs Arg - L: - .endmacro - - .macro ble Arg - beq Arg - bcc Arg - .endmacro -</verb></tscreen> - - -<sect1><tt>.MACPACK longbranch</tt><p> - -This macro package defines long conditional jumps. They are named like the -short counterpart but with the 'b' replaced by a 'j'. Here is a sample -definition for the "<tt/jeq/" macro, the other macros are built using the same -scheme: - -<tscreen><verb> - .macro jeq Target - .if .def(Target) .and ((*+2)-(Target) <= 127) - beq Target - .else - bne *+5 - jmp Target - .endif - .endmacro -</verb></tscreen> - -All macros expand to a short branch, if the label is already defined (back -jump) and is reachable with a short jump. Otherwise the macro expands to a -conditional branch with the branch condition inverted, followed by an absolute -jump to the actual branch target. - -The package defines the following macros: - -<tscreen><verb> - jeq, jne, jmi, jpl, jcs, jcc, jvs, jvc -</verb></tscreen> - - - -<sect1><tt>.MACPACK atari</tt><p> - -The atari macro package will define a macro named <tt/scrcode/. It takes a -string as argument and places this string into memory translated into screen -codes. - - -<sect1><tt>.MACPACK cbm</tt><p> - -The cbm macro package will define a macro named <tt/scrcode/. It takes a -string as argument and places this string into memory translated into screen -codes. - - -<sect1><tt>.MACPACK cpu</tt><p> - -This macro package does not define any macros but constants used to examine -the value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable. For -each supported CPU a constant similar to - -<tscreen><verb> - CPU_6502 - CPU_65SC02 - CPU_65C02 - CPU_65816 - CPU_SUNPLUS - CPU_SWEET16 - CPU_HUC6280 -</verb></tscreen> - -is defined. These constants may be used to determine the exact type of the -currently enabled CPU. In addition to that, for each CPU instruction set, -another constant is defined: - -<tscreen><verb> - CPU_ISET_6502 - CPU_ISET_65SC02 - CPU_ISET_65C02 - CPU_ISET_65816 - CPU_ISET_SUNPLUS - CPU_ISET_SWEET16 - CPU_ISET_HUC6280 -</verb></tscreen> - -The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may -be checked with <tt/<ref id="operators" name=".BITAND">/ to determine if the -currently enabled CPU supports a specific instruction set. For example the -65C02 supports all instructions of the 65SC02 CPU, so it has the -<tt/CPU_ISET_65SC02/ bit set in addition to its native <tt/CPU_ISET_65C02/ -bit. Using - -<tscreen><verb> - .if (.cpu .bitand CPU_ISET_65SC02) - lda (sp) - .else - ldy #$00 - lda (sp),y - .endif -</verb></tscreen> - -it is possible to determine if the - -<tscreen><verb> - lda (sp) -</verb></tscreen> - -instruction is supported, which is the case for the 65SC02, 65C02 and 65816 -CPUs (the latter two are upwards compatible to the 65SC02). - - - -<sect>Predefined constants<label id="predefined-constants"><p> - -For better orthogonality, the assembler defines similar symbols as the -compiler, depending on the target system selected: - -<itemize> -<item><tt/__APPLE2__/ - Target system is <tt/apple2/ -<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/ -<item><tt/__ATARI__/ - Target system is <tt/atari/ -<item><tt/__ATMOS__/ - Target system is <tt/atmos/ -<item><tt/__BBC__/ - Target system is <tt/bbc/ -<item><tt/__C128__/ - Target system is <tt/c128/ -<item><tt/__C16__/ - Target system is <tt/c16/ -<item><tt/__C64__/ - Target system is <tt/c64/ -<item><tt/__CBM__/ - Target is a Commodore system -<item><tt/__CBM510__/ - Target system is <tt/cbm510/ -<item><tt/__CBM610__/ - Target system is <tt/cbm610/ -<item><tt/__GEOS__/ - Target system is <tt/geos/ -<item><tt/__LUNIX__/ - Target system is <tt/lunix/ -<item><tt/__NES__/ - Target system is <tt/nes/ -<item><tt/__PET__/ - Target system is <tt/pet/ -<item><tt/__PLUS4__/ - Target system is <tt/plus4/ -<item><tt/__SUPERVISION__/ - Target system is <tt/supervision/ -<item><tt/__VIC20__/ - Target system is <tt/vic20/ -</itemize> - - -<sect>Structs and unions<label id="structs"><p> - -<sect1>Structs and unions Overview<p> - -Structs and unions are special forms of <ref id="scopes" name="scopes">. They -are to some degree comparable to their C counterparts. Both have a list of -members. Each member allocates storage and may optionally have a name, which, -in case of a struct, is the offset from the beginning and, in case of a union, -is always zero. - - -<sect1>Declaration<p> - -Here is an example for a very simple struct with two members and a total size -of 4 bytes: - -<tscreen><verb> - .struct Point - xcoord .word - ycoord .word - .endstruct -</verb></tscreen> - -A union shares the total space between all its members, its size is the same -as that of the largest member. The offset of all members relative to the union -is zero. - -<tscreen><verb> - .union Entry - index .word - ptr .addr - .endunion -</verb></tscreen> - -A struct or union must not necessarily have a name. If it is anonymous, no -local scope is opened, the identifiers used to name the members are placed -into the current scope instead. - -A struct may contain unnamed members and definitions of local structs. The -storage allocators may contain a multiplier, as in the example below: - -<tscreen><verb> - .struct Circle - .struct Point - .word 2 ; Allocate two words - .endstruct - Radius .word - .endstruct -</verb></tscreen> - - -<sect1>The <tt/.TAG/ keyword<p> - -Using the <ref id=".TAG" name=".TAG"> keyword, it is possible to reserve space -for an already defined struct or unions within another struct: - -<tscreen><verb> - .struct Point - xcoord .word - ycoord .word - .endstruct - - .struct Circle - Origin .tag Point - Radius .byte - .endstruct -</verb></tscreen> - -Space for a struct or union may be allocated using the <ref id=".TAG" -name=".TAG"> directive. - -<tscreen><verb> - C: .tag Circle -</verb></tscreen> - -Currently, members are just offsets from the start of the struct or union. To -access a field of a struct, the member offset has to be added to the address -of the struct itself: - -<tscreen><verb> - lda C+Circle::Radius ; Load circle radius into A -</verb></tscreen> - -This may change in a future version of the assembler. - - -<sect1>Limitations<p> - -Structs and unions are currently implemented as nested symbol tables (in fact, -they were a by-product of the improved scoping rules). Currently, the -assembler has no idea of types. This means that the <ref id=".TAG" -name=".TAG"> keyword will only allocate space. You won't be able to initialize -variables declared with <ref id=".TAG" name=".TAG">, and adding an embedded -structure to another structure with <ref id=".TAG" name=".TAG"> will not make -this structure accessible by using the '::' operator. - - - -<sect>Module constructors/destructors<label id="condes"><p> - -<em>Note:</em> This section applies mostly to C programs, so the explanation -below uses examples from the C libraries. However, the feature may also be -useful for assembler programs. - - -<sect1>Module constructors/destructors Overview<p> - -Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref -id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" -name=".INTERRUPTOR"></tt> keywords it is possible to export functions in a -special way. The linker is able to generate tables with all functions of a -specific type. Such a table will <em>only</em> include symbols from object -files that are linked into a specific executable. This may be used to add -initialization and cleanup code for library modules, or a table of interrupt -handler functions. - -The C heap functions are an example where module initialization code is used. -All heap functions (<tt>malloc</tt>, <tt>free</tt>, ...) work with a few -variables that contain the start and the end of the heap, pointers to the free -list and so on. Since the end of the heap depends on the size and start of the -stack, it must be initialized at runtime. However, initializing these -variables for programs that do not use the heap are a waste of time and -memory. - -So the central module defines a function that contains initialization code and -exports this function using the <tt/.CONSTRUCTOR/ statement. If (and only if) -this module is added to an executable by the linker, the initialization -function will be placed into the table of constructors by the linker. The C -startup code will call all constructors before <tt/main/ and all destructors -after <tt/main/, so without any further work, the heap initialization code is -called once the module is linked in. - -While it would be possible to add explicit calls to initialization functions -in the startup code, the new approach has several advantages: - -<enum> -<item> -If a module is not included, the initialization code is not linked in and not -called. So you don't pay for things you don't need. - -<item> -Adding another library that needs initialization does not mean that the -startup code has to be changed. Before we had module constructors and -destructors, the startup code for all systems had to be adjusted to call the -new initialization code. - -<item> -The feature saves memory: Each additional initialization function needs just -two bytes in the table (a pointer to the function). - -</enum> - - -<sect1>Calling order<p> - -The symbols are sorted in increasing priority order by the linker when using -one of the builtin linker configurations, so the functions with lower -priorities come first and are followed by those with higher priorities. The C -library runtime subroutine that walks over the function tables calls the -functions starting from the top of the table - which means that functions with -a high priority are called first. - -So when using the C runtime, functions are called with high priority functions -first, followed by low priority functions. - - -<sect1>Pitfalls<p> - -When using these special symbols, please take care of the following: - -<itemize> - -<item> -The linker will only generate function tables, it will not generate code to -call these functions. If you're using the feature in some other than the -existing C environments, you have to write code to call all functions in a -linker generated table yourself. See the <tt/condes/ and <tt/callirq/ modules -in the C runtime for an example on how to do this. - -<item> -The linker will only add addresses of functions that are in modules linked to -the executable. This means that you have to be careful where to place the -condes functions. If initialization or an irq handler is needed for a group of -functions, be sure to place the function into a module that is linked in -regardless of which function is called by the user. - -<item> -The linker will generate the tables only when requested to do so by the -<tt/FEATURE CONDES/ statement in the linker config file. Each table has to -be requested separately. - -<item> -Constructors and destructors may have priorities. These priorities determine -the order of the functions in the table. If your initialization or cleanup code -does depend on other initialization or cleanup code, you have to choose the -priority for the functions accordingly. - -<item> -Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref -id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" -name=".INTERRUPTOR"></tt> statements, there is also a more generic command: -<tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to specify an -additional type. Predefined types are 0 (constructor), 1 (destructor) and 2 -(interruptor). The linker generates a separate table for each type on request. - -</itemize> - - -<sect>Porting sources from other assemblers<p> - -Sometimes it is necessary to port code written for older assemblers to ca65. -In some cases, this can be done without any changes to the source code by -using the emulation features of ca65 (see <tt><ref id=".FEATURE" -name=".FEATURE"></tt>). In other cases, it is necessary to make changes to the -source code. - -Probably the biggest difference is the handling of the <tt><ref id=".ORG" -name=".ORG"></tt> directive. ca65 generates relocatable code, and placement is -done by the linker. Most other assemblers generate absolute code, placement is -done within the assembler and there is no external linker. - -In general it is not a good idea to write new code using the emulation -features of the assembler, but there may be situations where even this rule is -not valid. - -<sect1>TASS<p> - -You need to use some of the ca65 emulation features to simulate the behaviour -of such simple assemblers. - -<enum> -<item>Prepare your sourcecode like this: - -<tscreen><verb> - ; if you want TASS style labels without colons - .feature labels_without_colons - - ; if you want TASS style character constants - ; ("a" instead of the default 'a') - .feature loose_char_term - - .word *+2 ; the cbm load address - - [yourcode here] -</verb></tscreen> - -notice that the two emulation features are mostly useful for porting -sources originally written in/for TASS, they are not needed for the -actual "simple assembler operation" and are not recommended if you are -writing new code from scratch. - -<item>Replace all program counter assignments (which are not possible in ca65 -by default, and the respective emulation feature works different from what -you'd expect) by another way to skip to memory locations, for example the -<tt><ref id=".RES" name=".RES"></tt> directive. - -<tscreen><verb> - ; *=$2000 - .res $2000-* ; reserve memory up to $2000 -</verb></tscreen> - -Please note that other than the original TASS, ca65 can never move the program -counter backwards - think of it as if you are assembling to disk with TASS. - -<item>Conditional assembly (<tt/.ifeq//<tt/.endif//<tt/.goto/ etc.) must be -rewritten to match ca65 syntax. Most importantly notice that due to the lack -of <tt/.goto/, everything involving loops must be replaced by -<tt><ref id=".REPEAT" name=".REPEAT"></tt>. - -<item>To assemble code to a different address than it is executed at, use the -<tt><ref id=".ORG" name=".ORG"></tt> directive instead of -<tt/.offs/-constructs. - -<tscreen><verb> - .org $1800 - - [floppy code here] - - .reloc ; back to normal -</verb></tscreen> - -<item>Then assemble like this: - -<tscreen><verb> - cl65 --start-addr 0x0ffe -t none myprog.s -o myprog.prg -</verb></tscreen> - -Note that you need to use the actual start address minus two, since two bytes -are used for the cbm load address. - -</enum> - - -<sect>Bugs/Feedback<p> - -If you have problems using the assembler, if you find any bugs, or if -you're doing something interesting with the assembler, I would be glad to -hear from you. Feel free to contact me by email -(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). - - - -<sect>Copyright<p> - -ca65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von -Bassewitz. For usage of the binaries and/or sources the following -conditions do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - - - -</article> - - - diff --git a/doc/ca65html.sgml b/doc/ca65html.sgml deleted file mode 100644 index 8b26be44c..000000000 --- a/doc/ca65html.sgml +++ /dev/null @@ -1,289 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>ca65html Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2007-10-2 - -<abstract> -ca65html is an assembly-source-to-HTML converter. It is very useful if you -want to publish your assembler sources in the web. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -ca65html converts assembly source files written for use with the <tt/<url -url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone -tool written in PERL; and as such, it does not understand the structure of -assembler sources in the same depth as ca65 does, so it may fail in very rare -cases. In all other cases, it generates very nice output. - - -<sect>Usage<p> - - -<sect1>Command line option overview<p> - -The HTML converter accepts the following options: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: ca65html [options] file ... -Options: - --bgcolor c Use background color c instead of #FFFFFF - --colorize Add color highlights to the output - --commentcolor c Use color c for comments instead of #B22222 - --crefs Generate references to the C source file(s) - --ctrlcolor c Use color c for directives instead of #228B22 - --cvttabs Convert tabs to spaces in the output - --help This text - --htmldir dir Specify directory for HTML files - --indexcols n Use n columns on index page (default 6) - --indexname file Use file for the index file instead of index.html - --indexpage Create an index page - --indextitle title Use title as the index title instead of Index - --keywordcolor c Use color c for keywords instead of #A020F0 - --linelabels Generate a linexxx HTML label for each line - --linenumbers Add line numbers to the output - --linkstyle style Use the given link style - --replaceext Replace source extension instead of appending .html - --textcolor c Use text color c instead of #000000 - --verbose Be more verbose ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<p> - -Here is a description of all the command line options: - -<descrip> - - <tag><tt>--bgcolor c</tt></tag> - - Set the background color. The argument c must be a valid HTML color, usually - given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are the - respective red, green, and blue parts as two-digit hex values. The default is - <tt/#FFFFFF/ (white). That color is used in the <tt/<body>/ of the - generated HTML output. - - - <tag><tt>--colorize</tt></tag> - - Colorize the output. The converter outputs processor instructions, assembler - control commands, and comments in different colors. - - - <tag><tt>--commentcolor c</tt></tag> - - Set the color used for comments. The argument c must be a valid HTML color, - usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are - the respective red, green, and blue parts as two-digit hex values. The - default is <tt/#B22222/ (red). - - Note that this option has no effect if <tt/--colorize/ is not also given. - - - <tag><tt>--crefs</tt></tag> - - Generate references to the C file, when a <tt/.dbg/ command is found with a - file name. The converter assumes that the C source was also converted into - HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and - lives in the same directory as the assembler file. If the <tt/.dbg/ - directive specifies a line, a link to the correct line in the C file is - generated, using a label in the form <tt/linexxx/, as it is created by - <tt/c2html/ by use of the <tt/-n/ option. - - - <tag><tt>--commentcolor c</tt></tag> - - Set the color used for assembler control commands. The argument c must be a - valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/, - where r, g, and b are the respective red, green, and blue parts as two-digit - hex values. The default is <tt/#228B22/ (green). - - Note that this option has no effect if <tt/--colorize/ is not also given. - - - <tag><tt>--cvttabs</tt></tag> - - Convert tabs in the input into spaces in the output, assuming the standard - tab width of 8. This is useful if the <tt/--linenumbers/ option is used to - retain the indentation. - - - <tag><tt>--help</tt></tag> - - Print the command line option summary shown above. - - - <tag><tt>--htmldir dir</tt></tag> - - Specify an output directory for the generated HTML files. - - - <tag><tt>--indexcols n</tt></tag> - - Use n columns on the index page. This option has no effect if used without - <tt/--indexpage/. - - - <tag><tt>--indexname name</tt></tag> - - Use another index file name instead of <tt/index.html/. This option has no - effect if used without <tt/--indexpage/. - - - <tag><tt>--indexpage</tt></tag> - - Causes the converter to generate an index page listing file names, and all - exports found in the converted files. - - - <tag><tt>--indextitle title</tt></tag> - - Use "title" as the title of the index page. This option has no effect if - used without <tt/--indexpage/. - - - <tag><tt>--keywordcolor c</tt></tag> - - Set the color used for processor instructions. The argument c must be a - valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/, - where r, g, and b are the respective red, green, and blue parts as two-digit - hex values. The default is <tt/#A020F0/ (purple). - - Note that this option has no effect if <tt/--colorize/ is not also given. - - <tag><tt>--linelabels</tt></tag> - - Generate a label for each line using the name <tt/linexxx/ where xxx is the - number of the line. - - Note: The converter will not make use of this label. Use this option if you - have other HTML pages referencing the converted assembler file. - - - <tag><tt>--linenumbers</tt></tag> - - Generate line numbers on the left side of the output. - - - <tag><tt>--linkstyle n</tt></tag> - - Influences the style used when generating links for imports. If n is zero - (the default), the converter creates a link to the actual symbol if it is - defined somewhere in the input files. If not, it creates a link to the - <tt/.import/ statement. If n is one, the converter will always generate a - HTML link to the <tt/.import/ statement. - - - <tag><tt>--replaceext</tt></tag> - - Replace the file extension of the input file instead of appending <tt/.html/ - when generating the output file name. - - - <tag><tt>--textcolor c</tt></tag> - - Set the color for normal text. The argument c must be a valid HTML color, - usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are - the respective red, green, and blue parts as two-digit hex values. The - default is <tt/#000000/ (black). This color is used in the <tt/<body>/ - of the generated HTML output. - - - <tag><tt>--verbose</tt></tag> - - Increase the converter verbosity. Without this option, ca65html is quiet - when working. If you have a slow machine and lots of files to convert, you - might like a little bit more progress information. - -</descrip> -<p> - - -<sect>Peculiarities<p> - -<sect1>Cross links<p> - -Since ca65html is able to generate links between modules, the best way to use -it is to supply all modules to it in one run, instead of running each file -separately through it. - - -<sect1>Include files<p> - -For now, ca65html will not read files included with <tt/.include/. Specifying -the include files as normal input files on the command line works in many -cases. - - -<sect1>Conversion errors<p> - -Since ca65html does not really parse the input, but does most of its work -applying text patterns, it doesn't know anything about scoping and advanced -features of the assembler. This means that it might miss a label. And, it -might choose the wrong color for an item, in rare cases. Because it's just a -tool for displaying sources in a nice form, I think that's OK. Anyway, if you -find a conversion problem, you can send me a short piece of example input code. -If possible, I will fix it. - - -<sect1>Colorization<p> - -While having colors in the output looks really nice, it has one drawback: - -<enum> - -<item>Because lots of <tt/<span>/ tags are created in the output, -the size of the output file literally will explode. It seems to be the price -that you have to pay for color. - -</enum> - - -<sect>Bugs/Feedback<p> - -If you have problems using the converter, if you find any bugs, or if you're -doing something interesting with the assembler, I would be glad to hear from -you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>Copyright<p> - -ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the -following conditions apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - - - -</article> - - - diff --git a/doc/cbm510.sgml b/doc/cbm510.sgml deleted file mode 100644 index 0dc842bc1..000000000 --- a/doc/cbm510.sgml +++ /dev/null @@ -1,301 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Commodore 510 (aka P500) specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> -<date>2006-05-22 - -<abstract> -An overview over the Commodore 510 runtime system as it is implemented for the -cc65 C compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the CBM 510 runtime system as it comes with -the cc65 C compiler. It describes the memory layout, CBM 510 specific header -files, available drivers, and any pitfalls specific to that platform. - -Please note that CBM 510 specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - -In addition to the Commodore 510 (named P128 in the U.S.), no other -machines are supported by this cc65 target. - - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the Commodore -510 target is a machine language program with a one line BASIC stub, which -transfers control to the machine language running in bank 0. This means that a -program can be loaded as BASIC program and started with RUN. It is of course -possible to change this behaviour by using a modified startup file and linker -config. - - - -<sect>Memory layout<p> - -cc65 generated programs for the Commodore 510 run in bank 0, the memory bank -reserved for BASIC programs. Since there are no ROMs in this memory bank, -kernal subroutines are either emulated or called by bank switching, which has -the disadvantage of being slow compared to a direct call. - -The default memory configuration for the CBM 510 allocates all memory between -$0002 and $FFF0 in bank 0 for the compiled program. Some space -in low memory is lost, because a separate hardware stack is set up in page 1, -and the kernal replacement functions need some more memory locations. A few -more pages are lost in high memory, because the runtime sets up a copy of the -character ROM, a text screen and a CBM compatible jump table at $FF81. -The main startup code is located at $0400, so about 54K of the complete -bank are actually usable for applications. - -Special locations: - -<descrip> - <tag/Stack/ - The C runtime stack is located at $FF81 and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing CBM 510 specific code may use the <tt/cbm510.h/ or -<tt/cbm.h/ header files. Using the later may be an option when writing code -for more than one CBM platform, since it includes <tt/cbm510.h/ and declares -several functions common to all CBM platforms. - -<sect1>CBM 510 specific functions<p> - -The functions listed below are special for the CBM 510. See the <htmlurl -url="funcref.html" name="function reference"> for declaration and usage. - -<itemize> -<item>peekbsys -<item>peekwsys -<item>pokebsys -<item>pokewsys -</itemize> - - -<sect1>CBM specific functions<p> - -Some functions are available for all (or at least most) of the Commodore -machines. See the <htmlurl url="funcref.html" name="function reference"> for -declaration and usage. - - -<itemize> -<item>cbm_close -<item>cbm_closedir -<item>cbm_k_setlfs -<item>cbm_k_setnam -<item>cbm_k_load -<item>cbm_k_save -<item>cbm_k_open -<item>cbm_k_close -<item>cbm_k_readst -<item>cbm_k_chkin -<item>cbm_k_ckout -<item>cbm_k_basin -<item>cbm_k_bsout -<item>cbm_k_clrch -<item>cbm_load -<item>cbm_open -<item>cbm_opendir -<item>cbm_read -<item>cbm_readdir -<item>cbm_save -<item>cbm_write -<item>get_tv -</itemize> - - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/cbm510.h/ header file do -allow access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can -therefore not be accessed like on other platforms. Please use one of the -<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to -access the I/O chips. Direct reads and writes to the structures named below -will <em>not</em> work! - -<descrip> - - <tag><tt/VIC/</tag> - The <tt/VIC/ structure allows access to the VIC II (the graphics - controller). See the <tt/_vic2.h/ header file located in the include - directory for the declaration of the structure. - - <tag><tt/SID/</tag> - The <tt/SID/ structure allows access to the SID (the sound interface - device). See the <tt/_sid.h/ header file located in the include directory - for the declaration of the structure. - - <tag><tt/ACIA/</tag> - Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable. - See the <tt/_6551.h/ header file located in the include directory for the - declaration of the structure. - - <tag><tt/CIA/</tag> - Access to the CIA chip is available via the <tt/CIA/ variable. See the - <tt/_6526.h/ header file located in the include directory for the - declaration of the structure. - - <tag><tt/TPI1, TPI2/</tag> - The two 6525 triport chips may be accessed by using this variable. See the - <tt/_6525.h/ header file located in the include directory for the - declaration of the structure. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -No graphics drivers are currently available for the Commodore 510. - - -<sect1>Extended memory drivers<p> - -<descrip> - <tag><tt/cbm510-ram.emd (cbm510_ram)/</tag> - A driver for the RAM in bank 1. Supports up to 255 pages with 256 bytes - each. -</descrip><p> - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/cbm510-std.joy (cbm510_stdjoy)/</tag> - Supports up to two standard joysticks connected to the joysticks port of - the Commodore 510. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -No mouse drivers are currently available for the Commodore 510. - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/cbm510-std.ser (cbm510_stdser)/</tag> - Driver for the 6551 ACIA chip built into the Commodore 510. Supports up to - 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. - Note that because of the peculiarities of the 6551 chip transmits are not - interrupt driven, and the transceiver blocks if the receiver asserts flow - control because of a full buffer. - -</descrip><p> - - -<sect>Limitations<label id="limitations"><p> - - -<sect1>Kernal and hardware access<p> - -Since the program runs in bank 0, and the kernal and all I/O chips are located -in bank 15, calling ROM routines or accessing hardware needs special code. The -cc65 runtime implements wrappers for all functions in the kernal jump table. -While this simplifies things, it should be noted that the wrappers do have -quite an impact on performance: A cross bank call has an extra 300µs -penalty added by the wrapper. - -<sect1>Interrupts<p> - -Compiled programs contain an interrupt handler that runs in the program bank. -This has several advantages, one of them being performance (see cross bank -call overhead mentioned above). However, this introduces one problem: -Interrupts are lost while the CPU executes code in the kernal bank. As a -result, the clock may go wrong and (worse) serial interrupts may get lost. - -Since the cc65 runtime does only call the kernal for disk I/O, this means that -a program should not do file I/O while it depends on interrupts. - - -<sect>Other hints<p> - -<sect1>Passing arguments to the program<p> - -Command line argument passing is currently not supported for the Commodore -510. - - -<sect1>Program return code<p> - -The program return code (signed char) is passed back to BASIC by use of the -<tt/ST/ variable. - - -<sect1>Interrupt handlers<p> - -The runtime for the Commodore 510 uses routines marked as <tt/.INTERRUPTOR/ -for interrupt handlers. Such routines must be written as simple machine -language subroutines and will be called automatically by the interrupt handler -code when they are linked into a program. See the discussion of the -<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/cbm610.sgml b/doc/cbm610.sgml deleted file mode 100644 index 5acb38a1a..000000000 --- a/doc/cbm610.sgml +++ /dev/null @@ -1,300 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Commodore 610 specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-12-16 - -<abstract> -An overview over the Commodore 610 runtime system as it is implemented for the -cc65 C compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the CBM 610 runtime system as it comes with -the cc65 C compiler. It describes the memory layout, CBM 610 specific header -files, available drivers, and any pitfalls specific to that platform. - -Please note that CBM 610 specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - -In addition to the Commodore 610 (named B40 in the U.S.), several other -machines are supported by this cc65 target, since they have identical -hardware: The Commodore 620 and 630 (more memory, additional coprocessor -card), and the Commodore 710, 720 and 730 (same hardware in another case with -a builtin monitor). - - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the Commodore -610 target is a machine language program with a one line BASIC stub, which -transfers control to the machine language running in bank 1. This means that a -program can be loaded as BASIC program and started with RUN. It is of course -possible to change this behaviour by using a modified startup file and linker -config. - - -<sect>Memory layout<p> - -cc65 generated programs for the Commodore 610 run in bank 1, the memory bank -reserved for BASIC programs. Since there are no ROMs in this memory bank, -kernal subroutines are either emulated or called by bank switching, which has -the disadvantage of being slow compared to a direct call. - -The default memory configuration for the CBM 610 allocates all memory between -$0002 and $FFF0 in bank 1 for the compiled program. Some space -in low memory is lost, because a separate hardware stack is set up in page 1, -and the kernal replacement functions need some more memory locations. A few -more bytes are lost in high memory, because the runtime sets up a CBM -compatible jump table at $FF81. The main startup code is located at -$0400, so about 63K of the complete bank are actually usable for -applications. - -Special locations: - -<descrip> - <tag/Stack/ - The C runtime stack is located at $FF81 and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing CBM 610 specific code may use the <tt/cbm610.h/ or -<tt/cbm.h/ header files. Using the later may be an option when writing code -for more than one CBM platform, since it includes <tt/cbm610.h/ and declares -several functions common to all CBM platforms. - -<sect1>CBM 610 specific functions<p> - -The functions listed below are special for the CBM 610. See the <htmlurl -url="funcref.html" name="function reference"> for declaration and usage. - -<itemize> -<item>peekbsys -<item>peekwsys -<item>pokebsys -<item>pokewsys -</itemize> - - -<sect1>CBM specific functions<p> - -Some functions are available for all (or at least most) of the Commodore -machines. See the <htmlurl url="funcref.html" name="function reference"> for -declaration and usage. - - -<itemize> -<item>cbm_close -<item>cbm_closedir -<item>cbm_k_setlfs -<item>cbm_k_setnam -<item>cbm_k_load -<item>cbm_k_save -<item>cbm_k_open -<item>cbm_k_close -<item>cbm_k_readst -<item>cbm_k_chkin -<item>cbm_k_ckout -<item>cbm_k_basin -<item>cbm_k_bsout -<item>cbm_k_clrch -<item>cbm_load -<item>cbm_open -<item>cbm_opendir -<item>cbm_read -<item>cbm_readdir -<item>cbm_save -<item>cbm_write -<item>get_tv -</itemize> - - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/cbm610.h/ header file do -allow access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can -therefore not be accessed like on other platforms. Please use one of the -<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to -access the I/O chips. Direct reads and writes to the structures named below -will <em>not</em> work! - -<descrip> - - <tag><tt/CRTC/</tag> - The <tt/CRTC/ structure allows access to the CRTC (the video controller). - See the <tt/_6545.h/ header file located in the include directory for the - declaration of the structure. - - <tag><tt/SID/</tag> The <tt/SID/ structure allows access to the SID (the - sound interface device). See the <tt/_sid.h/ header file located in the - include directory for the declaration of the structure. - - <tag><tt/ACIA/</tag> - Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable. - See the <tt/_6551.h/ header file located in the include directory for the - declaration of the structure. - - <tag><tt/CIA/</tag> - Access to the CIA chip is available via the <tt/CIA/ variable. See the - <tt/_6526.h/ header file located in the include directory for the - declaration of the structure. - - <tag><tt/TPI1, TPI2/</tag> - The two 6525 triport chips may be accessed by using this variable. See the - <tt/_6525.h/ header file located in the include directory for the - declaration of the structure. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -No graphics drivers are currently available for the Commodore 610 (and since -the machine has no graphics capabilities, chances for a graphics driver aren't -really good:-). - - -<sect1>Extended memory drivers<p> - -<descrip> - <tag><tt/cbm610-ram.emd (cbm610_ram)/</tag> - A driver for the RAM in bank 2. Supports up to 255 pages with 256 bytes - each. -</descrip><p> - - -<sect1>Joystick drivers<p> - -The Commodore 610 is a business machine and doesn't have joystick ports. There -are no drivers for the non existing ports available. - - - -<sect1>Mouse drivers<p> - -Currently no drivers available (in fact, the API for loadable mouse drivers -does not exist). - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/cbm610-std.ser (cbm610_stdser)/</tag> - Driver for the 6551 ACIA chip built into the Commodore 610. Supports up to - 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. - Note that because of the peculiarities of the 6551 chip transmits are not - interrupt driven, and the transceiver blocks if the receiver asserts flow - control because of a full buffer. - -</descrip><p> - - -<sect>Limitations<label id="limitations"><p> - - -<sect1>Kernal and hardware access<p> - -Since the program runs in bank 1, and the kernal and all I/O chips are located -in bank 15, calling ROM routines or accessing hardware needs special code. The -cc65 runtime implements wrappers for all functions in the kernal jump table. -While this simplifies things, it should be noted that the wrappers do have -quite an impact on performance: A cross bank call has an extra 300µs -penalty added by the wrapper. - -<sect1>Interrupts<p> - -Compiled programs contain an interrupt handler that runs in the program bank. -This has several advantages, one of them being performance (see cross bank -call overhead mentioned above). However, this introduces one problem: -Interrupts are lost while the CPU executes code in the kernal bank. As a -result, the clock may go wrong and (worse) serial interrupts may get lost. - -Since the cc65 runtime does only call the kernal for disk I/O, this means that -a program should not do file I/O while it depends on interrupts. - - -<sect>Other hints<p> - -<sect1>Passing arguments to the program<p> - -Command line argument passing is currently not supported for the Commodore -610. - - -<sect1>Program return code<p> - -The program return code (low byte) is passed back to BASIC by use of the -<tt/ST/ variable. - - -<sect1>Interrupt handlers<p> - -The runtime for the Commodore 610 uses routines marked as <tt/.INTERRUPTOR/ -for interrupt handlers. Such routines must be written as simple machine -language subroutines and will be called automatically by the interrupt handler -code when they are linked into a program. See the discussion of the -<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/cc65.sgml b/doc/cc65.sgml deleted file mode 100644 index bb1303909..000000000 --- a/doc/cc65.sgml +++ /dev/null @@ -1,1386 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>cc65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2000-09-03, 2001-10-02, 2005-08-01 - -<abstract> -cc65 is a C compiler for 6502 targets. It supports several 6502 based home -computers like the Commodore and Atari machines, but it is easily retargetable. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - - -<sect>Overview<p> - -cc65 was originally a C compiler for the Atari 8-bit machines written by -John R. Dunning. In prior releases I've described the compiler by listing -up the changes made by me. I have made many more changes in the meantime -(and rewritten major parts of the compiler), so I will no longer do that, -since the list would be too large and of no use to anyone. Instead I will -describe the compiler in respect to the ANSI/ISO C standard. - -There are separate documents named <url url="library.html"> and <url -url="funcref.html"> that cover the library that is available for the compiler. -If you know C, and are interested in doing actual programming, the library -documentation is probably of much more use than this document. - -If you need some hints for getting the best code out of the compiler, you -may have a look at <url url="coding.html"> which covers some code generation -issues. - - - -<sect>Usage<p> - -The compiler translates C files into files containing assembly code that -may be translated by the ca65 macroassembler (for more information about -the assembler, have a look at <url url="ca65.html">). - - -<sect1>Command line option overview<p> - -The compiler may be called as follows: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: cc65 [options] file -Short options: - -Cl Make local variables static - -Dsym[=defn] Define a symbol - -E Stop after the preprocessing stage - -I dir Set an include directory search path - -O Optimize code - -Oi Optimize code, inline more code - -Or Enable register variables - -Os Inline some known functions - -T Include source as comment - -V Print the compiler version number - -W warning[,...] Suppress warnings - -d Debug mode - -g Add debug info to object file - -h Help (this text) - -j Default characters are signed - -mm model Set the memory model - -o name Name the output file - -r Enable register variables - -t sys Set the target system - -v Increase verbosity - -Long options: - --add-source Include source as comment - --bss-name seg Set the name of the BSS segment - --check-stack Generate stack overflow checks - --code-name seg Set the name of the CODE segment - --codesize x Accept larger code by factor x - --cpu type Set cpu type (6502, 65c02) - --create-dep name Create a make dependency file - --create-full-dep name Create a full make dependency file - --data-name seg Set the name of the DATA segment - --debug Debug mode - --debug-info Add debug info to object file - --debug-opt name Debug optimization steps - --dep-target target Use this dependency target - --disable-opt name Disable an optimization step - --enable-opt name Enable an optimization step - --forget-inc-paths Forget include search paths - --help Help (this text) - --include-dir dir Set an include directory search path - --list-opt-steps List all optimizer steps and exit - --list-warnings List available warning types for -W - --local-strings Emit string literals immediately - --memory-model model Set the memory model - --register-space b Set space available for register variables - --register-vars Enable register variables - --rodata-name seg Set the name of the RODATA segment - --signed-chars Default characters are signed - --standard std Language standard (c89, c99, cc65) - --static-locals Make local variables static - --target sys Set the target system - --verbose Increase verbosity - --version Print the compiler version number - --writable-strings Make string literals writable ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<p> - -Here is a description of all the command line options: - -<descrip> - - <label id="option-bss-name"> - <tag><tt>--bss-name seg</tt></tag> - - Set the name of the bss segment. See also <tt/<ref id="pragma-bss-name" - name="#pragma bss-name">/. - - - <label id="option-check-stack"> - <tag><tt>--check-stack</tt></tag> - - Tells the compiler to generate code that checks for stack overflows. See - <tt/<ref id="pragma-check-stack" name="#pragma check-stack">/ for an - explanation of this feature. - - - <label id="option-code-name"> - <tag><tt>--code-name seg</tt></tag> - - Set the name of the code segment. See also <tt/<ref id="pragma-code-name" - name="#pragma code-name">/ - - - <label id="option-codesize"> - <tag><tt>--codesize x</tt></tag> - - This options allows finer control about speed vs. size decisions in the code - generation and optimization phases. It gives the allowed size increase - factor (in percent). The default is 100 when not using <tt/-Oi/ and 200 when - using <tt/-Oi/ (<tt/-Oi/ is the same as <tt/-O --codesize 200/). - - - <label id="option--cpu"> - <tag><tt>--cpu CPU</tt></tag> - - Set the CPU, the compiler generates code for. You may specify "6502" or - "65C02" as the CPU. The default depends on the selected target (see option - <tt/<ref id="option-t" name="-t">/). It is the 6502 CPU for most targets or - if no target has been set. Specifying 65C02 will use a few 65C02 - instructions when generating code. Don't expect too much from this option: - In most cases the difference in size and speed is just 1-2%. - - - <label id="option-create-dep"> - <tag><tt>--create-dep name</tt></tag> - - Tells the compiler to generate a file containing the dependency list for the - compiled module in makefile syntax. The output is written to a file with the - given name. The output does not include system include files (in angle - brackets). - - - <label id="option-create-full-dep"> - <tag><tt>--create-full-dep name</tt></tag> - - Tells the compiler to generate a file containing the dependency list for the - compiled module in makefile syntax. The output is written to a file with the - given name. The output does include system include files (in angle - brackets). - - - <label id="option-data-name"> - <tag><tt>--data-name seg</tt></tag> - - Set the name of the data segment. See also <tt/<ref id="pragma-data-name" - name="#pragma data-name">/ - - - <tag><tt>-d, --debug</tt></tag> - - Enables debug mode, something that should not be needed for mere - mortals:-) - - - <label id="option-dep-target"> - <tag><tt>--dep-target target</tt></tag> - - When generating a dependency file, don't use the actual output file as the - target of the dependency, but the file specified with this option. The - option has no effect if neither <tt/<ref id="option-create-dep" - name="--create-dep">/ nor <tt/<ref id="option-create-full-dep" - name="--create-full-dep">/ is specified. - - - <tag><tt>-D sym[=definition]</tt></tag> - - Define a macro on the command line. If no definition is given, the macro - is defined to the value "1". - - - <tag><tt>--forget-inc-paths</tt></tag> - - Forget the builtin include paths. This is most useful when building - customized C or runtime libraries, in which case the standard header - files should be ignored. - - - <tag><tt>-g, --debug-info</tt></tag> - - This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the - generated assembler code. This will cause the assembler to include all - symbols in a special section in the object file. - - - <tag><tt>-h, --help</tt></tag> - - Print the short option summary shown above. - - - <label id="option-list-warnings"> - <tag><tt>--list-warnings</tt></tag> - - List the names of warning types available for use with <tt><ref - id="option-W" name="-W"></tt>. - - - <label id="option-local-strings"> - <tag><tt>--local-strings</tt></tag> - - Emit string literals into the rodata segment as soon as they're encountered - in the source (even if you do nothing but get the sizeof those strings). The - default is to keep string literals until end of assembly, merge read only - literals if possible, and then output the literals into the data or rodata - segment that is active at that point. Use of this option prevents merging of - duplicate strings, but the options that change the name of one of the data - segments will work. - - You can also use <tt><ref id="pragma-local-strings" - name="#pragma local-strings"></tt> for fine grained control. - - - <tag><tt>-o name</tt></tag> - - Specify the name of the output file. If you don't specify a name, the - name of the C input file is used, with the extension replaced by ".s". - - - <label id="option-register-vars"> - <tag><tt>-r, --register-vars</tt></tag> - - <tt/-r/ will make the compiler honor the <tt/register/ keyword. Local - variables may be placed in registers (which are actually zero page - locations). There is some overhead involved with register variables, since - the old contents of the registers must be saved and restored. Since register - variables are of limited use without the optimizer, there is also a combined - switch: <tt/-Or/ will enable both, the optimizer and register variables. - - For more information about register variables see <ref id="register-vars" - name="register variables">. - - The compiler setting can also be changed within the source file by using - <tt/<ref id="pragma-register-vars" name="#pragma register-vars">/. - - - <label id="option-register-space"> - <tag><tt>--register-space</tt></tag> - - This option takes a numeric parameter and is used to specify, how much - zero page register space is available. Please note that just giving this - option will not increase or decrease by itself, it will just tell the - compiler about the available space. You will have to allocate that space - yourself using an assembler module with the necessary allocations, and a - linker configuration that matches the assembler module. The default value - for this option is 6 (bytes). - - If you don't know what all this means, please don't use this option. - - - <label id="option-rodata-name"> - <tag><tt>--rodata-name seg</tt></tag> - - Set the name of the rodata segment (the segment used for readonly data). - See also <tt/<ref id="pragma-rodata-name" name="#pragma rodata-name">/ - - <label id="option-signed-chars"> - <tag><tt>-j, --signed-chars</tt></tag> - - Using this option, you can make the default characters signed. Since the - 6502 has no provisions for sign extending characters (which is needed on - almost any load operation), this will make the code larger and slower. A - better way is to declare characters explicitly as "signed" if needed. You - can also use <tt><ref id="pragma-signed-chars" - name="#pragma signed-chars"></tt> for better control of this option. - - - <label id="option--standard"> - <tag><tt>--standard std</tt></tag> - - This option allows to set the language standard supported. The argument is - one of - <descrip> - <tag/c89/ - This disables anything that is illegal in C89/C90. Among those things - are <tt>//</tt> comments and the non-standard keywords without - underscores. Please note that cc65 is not a fully C89 compliant compiler - despite this option. A few more things (like floats) are missing. - - <tag/c99/ - This enables a few features from the C99 standard. With this option, - <tt>//</tt> comments are allowed. It will also cause warnings and even - errors in a few situations that are allowed with <tt/--standard c89/. - For example, a call to a function without a prototype is an error in - this mode. - - <tag/cc65/ - This is the default mode. It is like c99 mode, but additional features - are enabled. Among these are "void data", non-standard keywords without - the underlines, unnamed function parameters and the requirement for - main() to return an int. - </descrip> - - Please note that the compiler does not support the C99 standard and never - will. c99 mode is actually c89 mode with a few selected C99 extensions. - - - <label id="option-t"> - <tag><tt>-t target, --target target</tt></tag> - - This option is used to set the target system. The target system determines - the character set that is used for strings and character constants and the - default CPU. The CPU setting can be overriden by use of the <tt/<ref - id="option--cpu" name="--cpu">/ option. - - The following target systems are supported: - - <itemize> - <item>none - <item>apple2 - <item>apple2enh - <item>atari - <item>atmos - <item>c16 (works also for the c116 with memory up to 32K) - <item>c64 - <item>c128 - <item>cbm510 (CBM-II series with 40 column video) - <item>cbm610 (all CBM-II II computers with 80 column video) - <item>geos-apple - <item>geos-cbm - <item>lunix - <item>lynx - <item>nes - <item>pet (all CBM PET systems except the 2001) - <item>plus4 - <item>supervision - <item>vic20 - </itemize> - - <tag><tt>-v, --verbose</tt></tag> - - Using this option, the compiler will be somewhat more verbose if errors - or warnings are encountered. - - - <label id="option-writable-strings"> - <tag><tt>--writable-strings</tt></tag> - - Make string literals writable by placing them into the data segment instead - of the rodata segment. You can also use <tt><ref id="pragma-writable-strings" - name="#pragma writable-strings"></tt> to control this option from within - the source file. - - - <label id="option-static-locals"> - <tag><tt>-Cl, --static-locals</tt></tag> - - Use static storage for local variables instead of storage on the stack. - Since the stack is emulated in software, this gives shorter and usually - faster code, but the code is no longer reentrant. The difference between - <tt/-Cl/ and declaring local variables as static yourself is, that - initializer code is executed each time, the function is entered. So when - using - - <tscreen><verb> - void f (void) - { - unsigned a = 1; - ... - } - </verb></tscreen> - - the variable <tt/a/ will always have the value <tt/1/ when entering the - function and using <tt/-Cl/, while in - - <tscreen><verb> - void f (void) - { - static unsigned a = 1; - .... - } - </verb></tscreen> - - the variable <tt/a/ will have the value <tt/1/ only the first time that the - function is entered, and will keep the old value from one call of the - function to the next. - - You may also use <tt><ref id="pragma-static-locals" - name="#pragma static-locals"></tt> to change this setting in your - sources. - - - <label id="option-include-dir"> - <tag><tt>-I dir, --include-dir dir</tt></tag> - - Set a directory where the compiler searches for include files. You may - use this option multiple times to add more than one directory to the - search list. - - - <label id="option-O"> - <tag><tt>-O, -Oi, -Or, -Os</tt></tag> - - Enable an optimizer run over the produced code. - - Using <tt/-Oi/, the code generator will inline some code where otherwise a - runtime functions would have been called, even if the generated code is - larger. This will not only remove the overhead for a function call, but will - make the code visible for the optimizer. <tt/-Oi/ is an alias for - <tt/-O --codesize 200/. - - <tt/-Or/ will make the compiler honor the <tt/register/ keyword. Local - variables may be placed in registers (which are actually zero page - locations). See also the <tt/<ref id="option-register-vars" - name="--register-vars">/ command line option, and the <ref - id="register-vars" name="discussion of register variables"> below. - - Using <tt/-Os/ will force the compiler to inline some known functions from - the C library like strlen. Note: This has two consequences: - <p> - <itemize> - <item>You may not use names of standard C functions in your own code. If you - do that, your program is not standard compliant anyway, but using - <tt/-Os/ will actually break things. - <p> - <item>The inlined string and memory functions will not handle strings or - memory areas larger than 255 bytes. Similarly, the inlined <tt/is..()/ - functions will not work with values outside the char. range (such as - <tt/EOF/). - <p> - </itemize> - <p> - It is possible to concatenate the modifiers for <tt/-O/. For example, to - enable register variables and inlining of known functions, you may use - <tt/-Ors/. - - - <tag><tt>-T, --add-source</tt></tag> - - This include the source code as comments in the generated code. This is - normally not needed. - - - <tag><tt>-V, --version</tt></tag> - - Print the version number of the compiler. When submitting a bug report, - please include the operating system you're using, and the compiler - version. - - - <label id="option-W"> - <tag><tt>-W name[,name]</tt></tag> - - This option allows to control warnings generated by the compiler. It is - followed by a comma separated list of warnings that should be enabled or - disabled. To disable a warning, its name is prefixed by a minus sign. If - no such prefix exists, or the name is prefixed by a plus sign, the warning - is enabled. - - The following warning names are currently recognized: - <descrip> - <tag><tt/const-comparison/</tag> - Warn if the result of a comparison is constant. - <tag><tt/error/</tag> - Treat all warnings as errors. - <tag><tt/no-effect/</tag> - Warn about statements that don't have an effect. - <tag><tt/struct-param/</tag> - Warn when passing structs by value. - <tag><tt/unknown-pragma/</tag> - Warn about known #pragmas. - <tag><tt/unused-label/</tag> - Warn about unused labels. - <tag><tt/unused-param/</tag> - Warn about unused function parameters. - <tag><tt/unused-var/</tag> - Warn about unused variables. - </descrip> - - The full list of available warning names may be retrieved by using the - option <tt><ref id="option-list-warnings" name="--list-warnings"></tt>. - - You may also use <tt><ref id="pragma-warn" name="#pragma warn"></tt> to - control this setting for smaller pieces of code from within your code. - -</descrip><p> - - -<sect>Input and output<p> - -The compiler will accept one C file per invocation and create a file with -the same base name, but with the extension replaced by ".s". The output -file contains assembler code suitable for the use with the ca65 macro -assembler. - -Include files in single quotes are searched in the following places: -<enum> -<item>The current directory. -<item>The value of the environment variable <tt/CC65_INC/ if it is defined. -<item>Any directory added with the <tt/-I/ option on the command line. -</enum> - -Include files in angle brackets are searched in the following places: -<enum> -<item>A compiled in directory which is often <tt>/usr/lib/cc65/include</tt> on - Linux systems. -<item>The value of the environment variable <tt/CC65_INC/ if it is defined. -<item>A subdirectory named <tt/include/ of the directory defined in the - environment variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt/-I/ option on the command line. -</enum> - - - -<sect>Differences to the ISO standard<p> - -Apart from the things listed below, the compiler does support additional -keywords, has several functions in the standard headers with names outside the -reserved namespace and a few syntax extensions. All these can be disabled with -the <tt><ref id="option--standard" name="--standard"></tt> command line -option. Its use for maximum standards compatibility is advised. - -Here is a list of differences between the language, the compiler accepts, -and the one defined by the ISO standard: - -<itemize> - -<item> The datatypes "float" and "double" are not available. - <p> -<item> C Functions may not return structs (or unions), and structs may not - be passed as parameters by value. However, struct assignment *is* - possible. - <p> -<item> Part of the C library is available only with fastcall calling - conventions (see below). It means that you must not mix pointers to - those functions with pointers to user-written, not-fastcall functions. - <p> -<item> The <tt/volatile/ keyword doesn't have an effect. This is not as bad - as it sounds, since the 6502 has so few registers that it isn't - possible to keep values in registers anyway. - <p> -</itemize> - -There may be some more minor differences I'm currently not aware of. The -biggest problem is the missing float data type. With this limitation in -mind, you should be able to write fairly portable code. - - - -<sect>Extensions<p> - -This cc65 version has some extensions to the ISO C standard. - -<itemize> - -<item> The compiler allows to insert assembler statements into the output - file. The syntax is - - <tscreen><verb> - asm (<string literal>[, optional parameters]) ; - </verb></tscreen> - or - <tscreen><verb> - __asm__ (<string literal>[, optional parameters]) ; - </verb></tscreen> - - The first form is in the user namespace and is disabled if the <tt/-A/ - switch is given. - - There is a whole section covering inline assembler statements, - <ref id="inline-asm" name="see there">. - <p> - -<item> There is a special calling convention named "fastcall". - The syntax for a function declaration using fastcall is - - <tscreen><verb> - <return type> fastcall <function name> (<parameter list>) - </verb></tscreen> - or - <tscreen><verb> - <return type> __fastcall__ <function name> (<parameter list>) - </verb></tscreen> - An example would be - <tscreen><verb> - void __fastcall__ f (unsigned char c) - </verb></tscreen> - The first form of the fastcall keyword is in the user namespace and can - therefore be disabled with the <tt><ref id="option--standard" - name="--standard"></tt> command line option. - - For functions declared as <tt/fastcall/, the rightmost parameter is not - pushed on the stack but left in the primary register when the function - is called. This will reduce the cost when calling assembler functions - significantly, especially when the function itself is rather small. - <p> - -<item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/. - Both refer to the primary register that is used by the compiler to - evaluate expressions or return function results. <tt/__AX__/ is of - type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/ - respectively. The pseudo variables may be used as lvalue and rvalue as - every other variable. They are most useful together with short - sequences of assembler code. For example, the macro - - <tscreen><verb> - #define hi(x) \ - (__AX__ = (x), \ - asm ("txa"), \ - asm ("ldx #$00"), \ - __AX__) - </verb></tscreen> - - will give the high byte of any unsigned value. - <p> - -<item> Inside a function, the identifier <tt/__func__/ gives the name of the - current function as a string. Outside of functions, <tt/__func__/ is - undefined. - Example: - - <tscreen><verb> - #define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s); - </verb></tscreen> - - The macro will print the name of the current function plus a given - string. - <p> - -<item> cc65 allows the initialization of <tt/void/ variables. This may be - used to create variable structures that are more compatible with - interfaces written for assembler languages. Here is an example: - - <tscreen><verb> - void GCmd = { (char)3, (unsigned)0x2000, (unsigned)0x3000 }; - </verb></tscreen> - - This will be translated as follows: - - <tscreen><verb> - _GCmd: - .byte 3 - .word $2000 - .word $3000 - </verb></tscreen> - - Since the variable is of type <tt/void/ you may not use it as is. - However, taking the address of the variable results in a <tt/void*/ - which may be passed to any function expecting a pointer. - - See the <url url="geos.html" name="GEOS library document"> for examples - on how to use this feature. - <p> - -<item> cc65 implements flexible array struct members as defined in the C99 ISO - standard. As an extension, these fields may be initialized. There are - several exceptions, however (which is probably the reason why the - standard does not define this feature, because it is highly - unorthogonal). Flexible array members cannot be initialized ... - - <itemize> - <item>... when defining an array of structs with flexible - members. - <item>... if such a struct is a member field of another struct - which is not the last field. - <item>... if the struct which contains a flexible array member is - declared as <tt/register/, and the size and compiler settings - do allow the compiler actually to place the struct into the - register bank in the zero page. - </itemize> - - Please note that -- as defined in the ISO C standard -- the <tt/sizeof/ - operator returns the struct size with the flexible array member having - size zero, even if it is initialized. - <p> - -</itemize> -<p> - - -<sect>Predefined macros<p> - -The compiler defines several macros at startup: - -<descrip> - <tag><tt>__APPLE2__</tt></tag> - - This macro is defined if the target is the Apple ][ (-t apple2). - - <tag><tt>__APPLE2ENH__</tt></tag> - - This macro is defined if the target is the enhanced Apple //e (-t apple2enh). - - <tag><tt>__ATARI__</tt></tag> - - This macro is defined if the target is one of the Atari computers - (400/800/130XL/800XL). - - <tag><tt>__ATMOS__</tt></tag> - - This macro is defined if the target is the Oric Atmos (-t atmos). - - <tag><tt>__C128__</tt></tag> - - This macro is defined if the target is the c128 (-t c128). - - <tag><tt>__C16__</tt></tag> - - This macro is defined if the target is the c16 (-t c16). - - <tag><tt>__C64__</tt></tag> - - This macro is defined if the target is the c64 (-t c64). - - <tag><tt>__CBM__</tt></tag> - - This macro is defined if the target system is one of the CBM targets. - - <tag><tt>__CBM510__</tt></tag> - - This macro is defined if the target is the CBM 500 series of computers. - - <tag><tt>__CBM610__</tt></tag> - - This macro is defined if the target is one of the CBM 600/700 family of - computers (called B series in the US). - - <tag><tt>__CC65__</tt></tag> - - This macro is always defined. Its value is the version number of the - compiler in hex. For example, version 2.10.1 of the compiler has this macro - defined as <tt/0x02A1/. - - <tag><tt>__CC65_STD__</tt></tag> - - This macro is defined to one of the following depending on the <tt><ref - id="option--standard" name="--standard"></tt> command line option: - <itemize> - <item><tt/__CC65_STD_C89__/ - <item><tt/__CC65_STD_C99__/ - <item><tt/__CC65_STD_CC65__/ - </itemize> - - <tag><tt>__DATE__</tt></tag> - - This macro expands to the date of translation of the preprocessing - translation unit in the form "Mmm dd yyyy". - - <tag><tt>__FILE__</tt></tag> - - This macro expands to a string containing the name of the C source file. - - <tag><tt>__GEOS__</tt></tag> - - This macro is defined if you are compiling for the GEOS system (-t geos). - - <tag><tt>__LINE__</tt></tag> - - This macro expands to the current line number. - - <tag><tt>__LUNIX__</tt></tag> - - This macro is defined if you are compiling for the LUnix system (-t lunix). - - <tag><tt>__LYNX__</tt></tag> - - This macro is defined if the target is the Atari Lynx (-t lynx). - - <tag><tt>__NES__</tt></tag> - - This macro is defined if the target is the NES (-t nes). - - <tag><tt>__OPT__</tt></tag> - - Is defined if the compiler was called with the <tt/-O/ command line option. - - <tag><tt>__OPT_i__</tt></tag> - - Is defined if the compiler was called with the <tt/-Oi/ command line option. - - <tag><tt>__OPT_r__</tt></tag> - - Is defined if the compiler was called with the <tt/-Or/ command line option. - - <tag><tt>__OPT_s__</tt></tag> - - Is defined if the compiler was called with the <tt/-Os/ command line option. - - <tag><tt>__PET__</tt></tag> - - This macro is defined if the target is the PET family of computers (-t pet). - - <tag><tt>__PLUS4__</tt></tag> - - This macro is defined if the target is the plus/4 (-t plus4). - - <tag><tt>__STDC_HOSTED__</tt></tag> - - This macro is expands to the integer constant 1. - - <tag><tt>__SUPERVISION__</tt></tag> - - This macro is defined if the target is the supervision (-t supervision). - - <tag><tt>__TIME__</tt></tag> - - This macro expands to the time of translation of the preprocessing - translation unit in the form "hh:mm:ss". - - <tag><tt>__VIC20__</tt></tag> - - This macro is defined if the target is the vic20 (-t vic20). -</descrip> - - -<sect>#pragmas<label id="pragmas"><p> - -The compiler understands some pragmas that may be used to change code -generation and other stuff. Some of these pragmas understand a special form: -If the first parameter is <tt/push/, the old value is saved onto a stack -before changing it. The value may later be restored by using the <tt/pop/ -parameter with the <tt/#pragma/. - -<sect1><tt>#pragma bss-name ([push,] <name>)</tt><label id="pragma-bss-name"><p> - - This pragma changes the name used for the BSS segment (the BSS segment - is used to store uninitialized data). The argument is a string enclosed - in double quotes. - - Note: The default linker configuration file does only map the standard - segments. If you use other segments, you have to create a new linker - configuration file. - - Beware: The startup code will zero only the default BSS segment. If you - use another BSS segment, you have to do that yourself, otherwise - uninitialized variables do not have the value zero. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - Example: - <tscreen><verb> - #pragma bss-name ("MyBSS") - </verb></tscreen> - - -<sect1><tt>#pragma charmap (<index>, <code>)</tt><label id="pragma-charmap"><p> - - Each literal string and each literal character in the source is translated - by use of a translation table. This translation table is preset when the - compiler is started depending on the target system, for example to map - ISO-8859-1 characters into PETSCII if the target is a commodore machine. - - This pragma allows to change entries in the translation table, so the - translation for individual characters, or even the complete table may be - adjusted. - - Both arguments are assumed to be unsigned characters with a valid range of - 1-255. - - Beware of two pitfalls: - - <itemize> - <item>The character index is actually the code of the character in the - C source, so character mappings do always depend on the source - character set. This means that <tt/#pragma charmap/ is not - portable -- it depends on the build environment. - <item>While it is possible to use character literals as indices, the - result may be somewhat unexpected, since character literals are - itself translated. For this reason I would suggest to avoid - character literals and use numeric character codes instead. - </itemize> - - Example: - <tscreen><verb> - /* Use a space wherever an 'a' occurs in ISO-8859-1 source */ - #pragma charmap (0x61, 0x20); - </verb></tscreen> - - -<sect1><tt>#pragma check-stack ([push,] on|off)</tt><label id="pragma-check-stack"><p> - - Tells the compiler to insert calls to a stack checking subroutine to detect - stack overflows. The stack checking code will lead to somewhat larger and - slower programs, so you may want to use this pragma when debugging your - program and switch it off for the release version. If a stack overflow is - detected, the program is aborted. - - If the argument is "off", stack checks are disabled (the default), otherwise - they're enabled. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - -<sect1><tt>#pragma code-name ([push,] <name>)</tt><label id="pragma-code-name"><p> - - This pragma changes the name used for the CODE segment (the CODE segment - is used to store executable code). The argument is a string enclosed in - double quotes. - - Note: The default linker configuration file does only map the standard - segments. If you use other segments, you have to create a new linker - configuration file. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - Example: - <tscreen><verb> - #pragma code-name ("MyCODE") - </verb></tscreen> - - -<sect1><tt>#pragma codesize ([push,] <int>)</tt><label id="pragma-codesize"><p> - - This pragma allows finer control about speed vs. size decisions in the code - generation and optimization phase. It gives the allowed size increase factor - (in percent). The default is can be changed by use of the <tt/<ref - id="option-codesize" name="--codesize">/ compiler option. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - -<sect1><tt>#pragma data-name ([push,] <name>)</tt><label id="pragma-data-name"><p> - - This pragma changes the name used for the DATA segment (the DATA segment - is used to store initialized data). The argument is a string enclosed in - double quotes. - - Note: The default linker configuration file does only map the standard - segments. If you use other segments, you have to create a new linker - configuration file. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - Example: - <tscreen><verb> - #pragma data-name ("MyDATA") - </verb></tscreen> - - -<sect1><tt>#pragma local-strings ([push,] on|off)</tt><label id="pragma-local-strings"><p> - - When "on", emit string literals to the data segment when they're encountered - in the source. The default ("off") is to keep string literals until end of - assembly, merge read only literals if possible, and then output the literals - into the data or rodata segment that is active at that point. - - Using this <tt/#pragma/ it is possible to control the behaviour from within - the source. When <tt/#pragma local-strings/ is active, string literals are - output immediately, which means that they go into the currently active data - or rodata segment, but cannot be merged. When inactive, string literals are - remembered and output as a whole when translation is finished. - - -<sect1><tt>#pragma optimize ([push,] on|off)</tt><label id="pragma-optimize"><p> - - Switch optimization on or off. If the argument is "off", optimization is - disabled, otherwise it is enabled. Please note that this pragma only effects - whole functions. The setting in effect when the function is encountered will - determine if the generated code is optimized or not. - - Optimization and code generation is also controlled by the <ref - id="pragma-codesize" name="codesize pragma">. - - The default is "off", but may be changed with the <tt/<ref name="-O" - id="option-O">/ compiler option. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - -<sect1><tt>#pragma rodata-name ([push,] <name>)</tt><label id="pragma-rodata-name"><p> - - This pragma changes the name used for the RODATA segment (the RODATA - segment is used to store readonly data). The argument is a string - enclosed in double quotes. - - Note: The default linker configuration file does only map the standard - segments. If you use other segments, you have to create a new linker - configuration file. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - Example: - <tscreen><verb> - #pragma rodata-name ("MyRODATA") - </verb></tscreen> - - -<sect1><tt>#pragma regvaraddr ([push,] on|off)</tt><label id="pragma-regvaraddr"><p> - - The compiler does not allow to take the address of register variables. - The regvaraddr pragma changes this. Taking the address of a register - variable is allowed after using this pragma with "on" as argument. - Using "off" as an argument switches back to the default behaviour. - - Beware: The C standard does not allow taking the address of a variable - declared as register. So your programs become non-portable if you use - this pragma. In addition, your program may not work. This is usually the - case if a subroutine is called with the address of a register variable, - and this subroutine (or a subroutine called from there) uses - register variables. So be careful with this #pragma. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - Example: - <tscreen><verb> - #pragma regvaraddr(on) /* Allow taking the address - * of register variables - */ - </verb></tscreen> - - -<sect1><tt>#pragma register-vars ([push,] on|off)</tt><label id="pragma-register-vars"><p> - - Enables or disables use of register variables. If register variables are - disabled (the default), the <tt/register/ keyword is ignored. Register - variables are explained in more detail in <ref id="register-vars" name="a separate - chapter">. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - -<sect1><tt>#pragma signed-chars ([push,] on|off)</tt><label id="pragma-signed-chars"><p> - - Changes the signedness of the default character type. If the argument is - "on", default characters are signed, otherwise characters are unsigned. The - compiler default is to make characters unsigned since this creates a lot - better code. This default may be overridden by the <tt/<ref - name="--signed-chars" id="option-signed-chars">/ command line option. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - -<sect1><tt>#pragma static-locals ([push,] on|off)</tt><label id="pragma-static-locals"<p> - - Use variables in the bss segment instead of variables on the stack. This - pragma changes the default set by the compiler option <tt/<ref - name="--static-locals" id="option-static-locals">/. If the argument is "on", - local variables are allocated in the BSS segment, leading to shorter and in - most cases faster, but non-reentrant code. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - -<sect1><tt>#pragma warn (name, [push,] on|off)</tt><label id="pragma-warn"><p> - - Switch compiler warnings on or off. "name" is the name of a warning (see the - <tt/<ref name="-W" id="option-W">/ compiler option for a list). The name is - either followed by "pop", which restores the last pushed state, or by "on" or - "off", optionally preceeded by "push" to push the current state before - changing it. - - Example: - <tscreen><verb> - /* Don't warn about the unused parameter in function func */ - #pragma warn (unused-param, push, off) - static int func (int unused) - { - return 0; - } - #pragma warn (unused-param, pop) - </verb></tscreen> - -<sect1><tt>#pragma writable-strings ([push,] on|off)</tt><label id="pragma-writable-strings"><p> - - Changes the storage location of string literals. For historical reasons, - the C standard defines that string literals are of type "char[]", but - writing to such a literal causes undefined behaviour. Most compilers - (including cc65) place string literals in the read-only data segment, which - may cause problems with old C code that writes to string literals. - - Using this pragma (or the corresponding command line option <tt/<ref - name="--writable-strings" id="option-writable-strings">/) causes the - literals to be placed in the data segment so they can be written to without - worry. - - The <tt/#pragma/ understands the push and pop parameters as explained above. - - -<sect1><tt>#pragma zpsym (<name>)</tt><p> - - Tell the compiler that the -- previously as external declared -- symbol with - the given name is a zero page symbol (usually from an assembler file). - The compiler will create a matching import declaration for the assembler. - - Example: - <tscreen><verb> - extern int foo; - #pragma zpsym ("foo"); /* foo is in the zeropage */ - </verb></tscreen> - - - - -<sect>Register variables<label id="register-vars"><p> - -The runtime for all supported platforms has 6 bytes of zero page space -available for register variables (this could be increased, but I think it's a -good value). So you can declare register variables up to a total size of 6 per -function. The compiler will allocate register space on a "first come, first -served" base and convert any <tt/register/ declarations that exceed the -available register space silently to <tt/auto/. Parameters can also be -declared as <tt/register/, this will in fact give slightly shorter code than -using a register variable. - -Since a function must save the current values of the registers on entry and -restore them on exit, there is an overhead associated with register variables, -and this overhead is quite high (about 20 bytes per variable). This means that -just declaring anything as <tt/register/ is not a good idea. - -The best use for register variables are pointers, especially those that point -to structures. The magic number here is about 3 uses of a struct field: If the -function contains this number or even more, the generated code will be usually -shorter and faster when using a register variable for the struct pointer. The -reason for this is that the register variable can in many cases be used as a -pointer directly. Having a pointer in an auto variable means that this pointer -must first be copied into a zero page location, before it can be dereferenced. - -Second best use for register variables are counters. However, there is not -much difference in the code generated for counters, so you will need at least -100 operations on this variable (for example in a loop) to make it worth the -trouble. The only savings you get here are by the use of a zero page variable -instead of one on the stack or in the data segment. - -Register variables must be explicitly enabled, either by using <tt/<ref -name="-Or" id="option-O">/ or <tt/<ref name="--register-vars" -id="option-register-vars">/ on the command line or by use of <tt/<ref -name="#pragma register-vars" id="pragma-register-vars">/. Register variables -are only accepted on function top level, register variables declared in -interior blocks are silently converted to <tt/auto/. With register variables -disabled, all variables declared as <tt/register/ are actually auto variables. - -Please take care when using register variables: While they are helpful and can -lead to a tremendous speedup when used correctly, improper usage will cause -bloated code and a slowdown. - - - -<sect>Inline assembler<label id="inline-asm"><p> - -The compiler allows to insert assembler statements into the output file. The -syntax is - -<tscreen><verb> - asm (<string literal>[, optional parameters]) ; -</verb></tscreen> -or -<tscreen><verb> - __asm__ (<string literal>[, optional parameters]) ; -</verb></tscreen> -<p> - -The first form is in the user namespace and is disabled by <tt><ref -id="option--standard" name="--standard"></tt> if the argument is not <tt/cc65/. - -The asm statement may be used inside a function and on global file level. An -inline assembler statement is a primary expression, so it may also be used as -part of an expression. Please note however that the result of an expression -containing just an inline assembler statement is always of type <tt/void/. - -The contents of the string literal are preparsed by the compiler and inserted -into the generated assembly output, so that the can be further processed by -the backend and especially the optimizer. For this reason, the compiler does -only allow regular 6502 opcodes to be used with the inline assembler. Pseudo -instructions (like <tt/.import/, <tt/.byte/ and so on) are <em/not/ allowed, -even if the ca65 assembler (which is used to translate the generated assembler -code) would accept them. The builtin inline assembler is not a replacement for -the full blown macro assembler which comes with the compiler. - -Note: Inline assembler statements are subject to all optimizations done by the -compiler. There is currently no way to protect an inline assembler statement -from being moved or removed completely by the optimizer. If in doubt, check -the generated assembler output, or disable optimizations. - -The string literal may contain format specifiers from the following list. For -each format specifier, an argument is expected which is inserted instead of -the format specifier before passing the assembly code line to the backend. - -<itemize> - <item><tt/%b/ - Numerical 8-bit value - <item><tt/%w/ - Numerical 16-bit value - <item><tt/%l/ - Numerical 32-bit value - <item><tt/%v/ - Assembler name of a global variable or function - <item><tt/%o/ - Stack offset of a local variable - <item><tt/%g/ - Assembler name of a C label - <item><tt/%s/ - The argument is converted to a string - <item><tt/%%/ - The % sign itself -</itemize><p> - -Using these format specifiers, you can access C <tt/#defines/, variables or -similar stuff from the inline assembler. For example, to load the value of -a C <tt/#define/ into the Y register, one would use - -<tscreen><verb> - #define OFFS 23 - __asm__ ("ldy #%b", OFFS); -</verb></tscreen> - -Or, to access a struct member of a static variable: - -<tscreen><verb> - typedef struct { - unsigned char x; - unsigned char y; - unsigned char color; - } pixel_t; - static pixel_t pixel; - __asm__ ("ldy #%b", offsetof(pixel_t, color)); - __asm__ ("lda %v,y", pixel); -</verb></tscreen> -<p> -The next example shows how to use global variables to exchange data between C -an assembler and how to handle assembler jumps: - -<tscreen><verb> - unsigned char globalSubA, globalSubB, globalSubResult; - - /* return a-b, return 255 if b>a */ - unsigned char sub (unsigned char a, unsigned char b) - { - globalSubA = a; - globalSubB = b; - __asm__ ("sec"); - __asm__ ("lda %v", globalSubA); - __asm__ ("sbc %v", globalSubB); - __asm__ ("bcs %g", jumpSubNoError); - __asm__ ("lda #$FF"); - jumpSubNoError: - __asm__ ("sta %v", globalSubResult); - return globalSubResult; - } -</verb></tscreen> -<p> - -Arrays can also be accessed: - -<tscreen><verb> - unsigned char globalSquareTable[] = { - 0, 1, 4, 9, 16, 25, 36, 49, 64, 81, - 100, 121, 144, 169, 196, 225 - }; - unsigned char globalSquareA, globalSquareResult; - - /* return a*a for a<16, else 255 */ - unsigned char square (unsigned char a) - { - if (a>15){ - return 255; - } - globalSquareA = a; - __asm__ ("ldx %v", globalSquareA); - __asm__ ("lda %v,x", globalSquareTable); - __asm__ ("sta %v", globalSquareResult); - return globalSquareResult; - } -</verb></tscreen> -<p> - -Note: Do not embed the assembler labels that are used as names of global -variables or functions into your asm statements. Code like this - -<tscreen><verb> - int foo; - int bar () { return 1; } - __asm__ ("lda _foo"); /* DON'T DO THAT! */ - ... - __asm__ ("jsr _bar"); /* DON'T DO THAT EITHER! */ -</verb></tscreen> -<p> - -may stop working if the way, the compiler generates these names is changed in -a future version. Instead use the format specifiers from the table above: - -<tscreen><verb> - __asm__ ("lda %v", foo); /* OK */ - ... - __asm__ ("jsr %v", bar); /* OK */ -</verb></tscreen> -<p> - - -<sect>Implementation-defined behavior<p> - -This section describes the behavior of cc65 when the standard describes the -behavior as implementation-defined. - -(to be done) - -<sect>Bugs/Feedback<p> - -If you have problems using the compiler, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>Copyright<p> - -This is the original compiler copyright: - -<tscreen><verb> --------------------------------------------------------------------------- - -*- Mode: Text -*- - - This is the copyright notice for RA65, LINK65, LIBR65, and other - Atari 8-bit programs. Said programs are Copyright 1989, by John R. - Dunning. All rights reserved, with the following exceptions: - - Anyone may copy or redistribute these programs, provided that: - - 1: You don't charge anything for the copy. It is permissable to - charge a nominal fee for media, etc. - - 2: All source code and documentation for the programs is made - available as part of the distribution. - - 3: This copyright notice is preserved verbatim, and included in - the distribution. - - You are allowed to modify these programs, and redistribute the - modified versions, provided that the modifications are clearly noted. - - There is NO WARRANTY with this software, it comes as is, and is - distributed in the hope that it may be useful. - - This copyright notice applies to any program which contains - this text, or the refers to this file. - - This copyright notice is based on the one published by the Free - Software Foundation, sometimes known as the GNU project. The idea - is the same as theirs, ie the software is free, and is intended to - stay that way. Everybody has the right to copy, modify, and re- - distribute this software. Nobody has the right to prevent anyone - else from copying, modifying or redistributing it. - --------------------------------------------------------------------------- -</verb></tscreen> - -Small parts of the compiler (parts of the preprocessor and main parser) are -still covered by this copyright. The main portion is covered by the usual -cc65 license, which reads: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> - diff --git a/doc/cl65.sgml b/doc/cl65.sgml deleted file mode 100644 index a574049cc..000000000 --- a/doc/cl65.sgml +++ /dev/null @@ -1,316 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>cl65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>01.08.2000, 27.11.2000, 02.10.2001 - -<abstract> -cl65 is the compile & link utility for cc65, the 6502 C compiler. It was -designed as a smart frontend for the C compiler (cc65), the assembler (ca65), -the object file converter (co65), and the linker (ld65). -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -cl65 is a frontend for cc65, ca65, co65 and ld65. While you may not use the -full power of the tools when calling them through cl65, most features are -available, and the use of cl65 is much simpler. - - -<sect>Basic Usage<p> - -The cl65 compile and link utility may be used to convert, compile, assemble -and link files. While the separate tools do just one step, cl65 knows how to -build object files from C files (by calling the compiler, then the assembler) -and other things. - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: cl65 [options] file [...] -Short options: - -c Compile and assemble but don't link - -d Debug mode - -g Add debug info - -h Help (this text) - -l name Create an assembler listing file - -m name Create a map file - -mm model Set the memory model - -o name Name the output file - -r Enable register variables - -t sys Set the target system - -u sym Force an import of symbol `sym' - -v Verbose mode - -vm Verbose map file - -C name Use linker config file - -Cl Make local variables static - -D sym[=defn] Define a preprocessor symbol - -I dir Set a compiler include directory path - -L path Specify a library search path - -Ln name Create a VICE label file - -O Optimize code - -Oi Optimize code, inline functions - -Or Optimize code, honour the register keyword - -Os Optimize code, inline known C funtions - -S Compile but don't assemble and link - -T Include source as comment - -V Print the version number - -W name[,...] Supress compiler warnings - -Wa options Pass options to the assembler - -Wl options Pass options to the linker - -Long options: - --add-source Include source as comment - --asm-args options Pass options to the assembler - --asm-define sym[=v] Define an assembler symbol - --asm-include-dir dir Set an assembler include directory - --bin-include-dir dir Set an assembler binary include directory - --bss-label name Define and export a BSS segment label - --bss-name seg Set the name of the BSS segment - --cc-args options Pass options to the compiler - --cfg-path path Specify a config file search path - --check-stack Generate stack overflow checks - --code-label name Define and export a CODE segment label - --code-name seg Set the name of the CODE segment - --codesize x Accept larger code by factor x - --config name Use linker config file - --cpu type Set cpu type - --create-dep name Create a make dependency file - --create-full-dep name Create a full make dependency file - --data-label name Define and export a DATA segment label - --data-name seg Set the name of the DATA segment - --debug Debug mode - --debug-info Add debug info - --feature name Set an emulation feature - --force-import sym Force an import of symbol `sym' - --forget-inc-paths Forget include search paths (compiler) - --help Help (this text) - --include-dir dir Set a compiler include directory path - --ld-args options Pass options to the linker - --lib file Link this library - --lib-path path Specify a library search path - --list-targets List all available targets - --listing name Create an assembler listing file - --list-bytes n Number of bytes per assembler listing line - --mapfile name Create a map file - --memory-model model Set the memory model - --module Link as a module - --module-id id Specify a module id for the linker - --o65-model model Override the o65 model - --obj file Link this object file - --obj-path path Specify an object file search path - --register-space b Set space available for register variables - --register-vars Enable register variables - --rodata-name seg Set the name of the RODATA segment - --signed-chars Default characters are signed - --standard std Language standard (c89, c99, cc65) - --start-addr addr Set the default start address - --static-locals Make local variables static - --target sys Set the target system - --version Print the version number - --verbose Verbose mode - --zeropage-label name Define and export a ZEROPAGE segment label - --zeropage-name seg Set the name of the ZEROPAGE segment ---------------------------------------------------------------------------- -</verb></tscreen> - -Most of the options have the same meaning than the corresponding compiler, -assembler or linker option. See the documentation for these tools for an -explanation. If an option is available for more than one of the tools, it -is set for all tools, where it is available. One example for this is <tt/-v/: -The compiler, the assembler and the linker are all called with the <tt/-v/ -switch. - -There are a few remaining options that control the behaviour of cl65: - -<descrip> - - <tag><tt>-S</tt></tag> - - This option forces cl65 to stop after the assembly step. This means that - C files are translated into assembler files, but nothing more is done. - Assembler files, object files and libraries given on the command line - are ignored. - - - <tag><tt>-c</tt></tag> - - This options forces cl65 to stop after the assembly step. This means - that C and assembler files given on the command line are translated into - object files, but there is no link step, and object files and libraries - given on the command line are ignored. - - - <tag><tt>-o name</tt></tag> - - The -o option is used for the target name in the final step. This causes - problems, if the linker will not be called, and there are several input - files on the command line. In this case, the name given with -o will be - used for all of them, which makes the option pretty useless. You - shouldn't use -o when more than one output file is created. - - - <tag><tt>-t sys, --target sys</tt></tag> - - The default for this option is different from the compiler and linker in the - case that the option is missing: While the other tools (compiler, assembler - and linker) will use the "none" system settings by default, cl65 will use - the C64 as a target system by default. This was chosen since most people - seem to use cc65 to develop for the C64. - - <tag><tt>-Wa options, --asm-args options</tt></tag> - - Pass options directly to the assembler. This may be used to pass options - that aren't directly supported by cl65. Several options may be separated by - commas, the commas are replaced by spaces when passing them to the - assembler. Beware: Passing arguments directly to the assembler may interfere - with some of the defaults, because cl65 doesn't parse the options passed. So - if cl65 supports an option by itself, do not pass this option to the - assembler by means of the <tt/-Wa/ switch. - - <tag><tt>-Wc options, --cc-args options</tt></tag> - - Pass options directly to the compiler. This may be used to pass options - that aren't directly supported by cl65. Several options may be separated by - commas, the commas are replaced by spaces when passing them to the - compiler. Beware: Passing arguments directly to the compiler may interfere - with some of the defaults, because cl65 doesn't parse the options passed. So - if cl65 supports an option by itself, do not pass this option to the - compiler by means of the <tt/-Wc/ switch. - - <tag><tt>-Wl options, --ld-args options</tt></tag> - - Pass options directly to the linker. This may be used to pass options that - aren't directly supported by cl65. Several options may be separated by - commas, the commas are replaced by spaces when passing them to the linker. - Beware: Passing arguments directly to the linker may interfere with some of - the defaults, because cl65 doesn't parse the options passed. So if cl65 - supports an option by itself, do not pass this option to the linker by means - of the <tt/-Wl/ switch. - -</descrip> - - - -<sect>More usage<p> - -Since cl65 was created to simplify the use of the cc65 development -package, it tries to be smart about several things. - -<itemize> - -<item> If you don't give a target system on the command line, cl65 - defaults to the C64. - -<item> When linking, cl65 will supply the names of the startup file and - library for the target system to the linker, so you don't have to do - that. - -<item> If the final step is the linker, and the name of the output file was - not explicitly given, cl65 will use the name of the first input file - without the extension, provided that the name of this file has an - extension. So you don't need to name the executable name in most - cases, just give the name of your "main" file as first input file. -</itemize> - -The command line is parsed from left to right, and the actual processing tool -(compiler, assembler, ...) is invoked whenever a file name is encountered. -This means that only the options to the left of a file name are in effect when -this file is processed. It does also mean that you're able to specify -different options for different files on the command line. As an example. - -<tscreen><verb> - cl65 -Oirs main.c -O -g module.c -</verb></tscreen> - -translates main.c with full optimization and module.c with less optimization -and debug info enabled. - -The type of an input file is derived from its extension: - -<itemize> -<item>C files: <tt/.c/ -<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/ -<item>Object files: <tt/.o/ <tt/.obj/ -<item>Libraries: <tt/.a/, <tt/.lib/ -<item>GEOS resource files: <tt/.grc/ -<item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/ -</itemize> - -Please note that the program cannot handle input files with unknown file -extensions. - - -<sect>Examples<p> - -The morse trainer software, which consists of one C file (morse.c) and one -assembler file (irq.s) will need the following separate steps to compile -into an executable named morse: - -<tscreen><verb> - cc65 -g -Oi -t c64 morse.c - ca65 -g morse.s - ca65 -g irq.s - ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib -</verb></tscreen> - -When using cl65, this is simplified to - -<tscreen><verb> - cl65 -g -Oi morse.c irq.s -</verb></tscreen> - -As a general rule, you may use cl65 instead of cc65 at most times, -especially in makefiles to build object files directly from C files. Use - -<tscreen><verb> - .c.o: - cl65 -g -Oi $< -</verb></tscreen> - -to do this. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the utility, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). - - - -<sect>Copyright<p> - -cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von -Bassewitz. For usage of the binaries and/or sources the following -conditions do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - - - -</article> - diff --git a/doc/co65.sgml b/doc/co65.sgml deleted file mode 100644 index 126ed56fd..000000000 --- a/doc/co65.sgml +++ /dev/null @@ -1,353 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>co65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>12.02.2003 - -<abstract> -co65 is an object file conversion utility. It converts o65 object files into -the native object file format used by the cc65 tool chain. Since o65 is the -file format used by cc65 for loadable drivers, the co65 utility allows (among -other things) to link drivers statically to the generated executables instead -of loading them from disk. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - - -<sect>Overview<p> - -co65 is an object file conversion utility. It converts o65 object files into -assembler files, which may be translated by ca65 to generate object files in -the native object file format used by the cc65 tool chain. - -Since loadable drivers used by the library that comes with cc65 use the o65 -relocatable object code format, using the co65 utility allows to link these -drivers statically. This enables the use of these drivers without loading -additional files from a disk or other secondary storage. - -Another use would be to link object files generated by other development tools -to projects using the cc65 tool chain, but this has not been tested until now, -since such tools are currently rare. - - - -<sect>Usage<p> - -The co65 utility converts one o65 file per run into one assembler files in -ca65 format. The utility tries to autodetect the type of the o65 input file -using the operating system identifier contained in the o65 option list. - - -<sect1>Command line option overview<p> - -The converter may be called as follows: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: co65 [options] file -Short options: - -V Print the version number - -g Add debug info to object file - -h Help (this text) - -m model Override the o65 model - -n Don't generate an output file - -o name Name the output file - -v Increase verbosity - -Long options: - --bss-label name Define and export a BSS segment label - --bss-name seg Set the name of the BSS segment - --code-label name Define and export a CODE segment label - --code-name seg Set the name of the CODE segment - --data-label name Define and export a DATA segment label - --data-name seg Set the name of the DATA segment - --debug-info Add debug info to object file - --help Help (this text) - --no-output Don't generate an output file - --o65-model model Override the o65 model - --verbose Increase verbosity - --version Print the version number - --zeropage-label name Define and export a ZEROPAGE segment label - --zeropage-name seg Set the name of the ZEROPAGE segment ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<p> - -Here is a description of all the command line options: - -<descrip> - - <tag><tt>--bss-label name</tt></tag> - - Set the label used to mark the start of the bss segment. When this option is - given, the label is also exported and may be accessed from other code. When - accessing such a label from C code, be sure to include the leading - underscore. If you don't need to access the bss segment, there's no need to - use this option. - - - <tag><tt>--bss-name seg</tt></tag> - - Set the name of the bss segment. The default name is "BSS" which is - compatible with the standard ld65 linker configurations. - - - <tag><tt>--code-label name</tt></tag> - - Set the label used to mark the start of the code segment. When this option - is given, the label is also exported and may be accessed from other code. - When accessing such a label from C code, be sure to include the leading - underscore. If you don't need to access the code segment, there's no need to - use this option. - - - <tag><tt>--code-name seg</tt></tag> - - Set the name of the code segment. The default name is "CODE" which is - compatible with the standard ld65 linker configurations. - - - <tag><tt>--data-label name</tt></tag> - - Set the label used to mark the start of the data segment. When this option - is given, the label is also exported and may be accessed from other code. - When accessing such a label from C code, be sure to include the leading - underscore. If you don't need to access the data segment, there's no need to - use this option. - - - <tag><tt>--data-name seg</tt></tag> - - Set the name of the data segment. The default name is "DATA" which is - compatible with the standard ld65 linker configurations. - - - <tag><tt>-d, --debug</tt></tag> - - Enables debug mode, something that should not be needed for mere mortals. - Currently the converter does only accept cc65 loadable modules generated by - ld65 when not in debug mode. Please note that correct conversion has never - been tested for o65 files from other sources, so be careful when using - <tt/-d/. - - - <tag><tt>-g, --debug-info</tt></tag> - - This will cause the converter to insert a <tt/.DEBUGINFO/ command into the - generated assembler code. This will cause the assembler to include all - symbols in a special section in the object file. - - - <tag><tt>-h, --help</tt></tag> - - Print the short option summary shown above. - - - <tag><tt>-m model, --o65-model model</tt></tag> - - Set an o65 model. This option changes the way, output is generated for the - given o65 file. For example, cc65 loadable drivers have a zero page segment, - but this segment must not be defined in the file itself, because the - standard module loader will overlay it with the zeropage space used by the - application that loads this module. So instead of allocating space in the - zero page segment, the converter will reference the start of the zero page - area used by the application. - - Currently, the following models are defined: - - <itemize> - <item>lunix - <item>os/a65 - <item>cc65-module - </itemize> - - The default is to autodetect the model to use from the input file, so - there's rarely a need to use this option. - - - <tag><tt>-n, --no-output</tt></tag> - - Don't do the actual conversion, just read in the o65 file checking for - problems. This option may be used in conjunction with <tt/--verbose/ to - view some information about the input file. - - - <tag><tt>-o name</tt></tag> - - Specify the name of the output file. If you don't specify a name, the - name of the o65 input file is used, with the extension replaced by ".s". - - - <tag><tt>-v, --verbose</tt></tag> - - Using this option, the converter will be somewhat more verbose and print - some information about the o65 input file (among other things). You may use - this option together with <tt/--no-output/ to just get the o65 info. - - - <tag><tt>-V, --version</tt></tag> - - Print the version number of the compiler. When submitting a bug report, - please include the operating system you're using, and the compiler - version. - - - <tag><tt>--zeropage-label name</tt></tag> - - Set the label used to mark the start of the zeropage segment. When this - option is given, the label is also exported and may be accessed from other - code. When accessing such a label from C code, be sure to include the - leading underscore. If you don't need to access the zeropage segment, - there's no need to use this option. - - - <tag><tt>--zeropage-name seg</tt></tag> - - Set the name of the zeropage segment. The default name is "ZEROPAGE" which is - compatible with the standard ld65 linker configurations. - -</descrip> - - -<sect>Input and output<p> - -The converter will accept one o65 file per invocation and create a file with -the same base name, but with the extension replaced by ".s". The output -file contains assembler code suitable for the use with the ca65 macro -assembler. - - -<sect>Converting loadable drivers<p> - -<sect1>Differences between static linking and runtime loading<p> - -One main use of the utility is conversion of loadable drivers, so they may be -linked statically to an application. Statically linking will cause a few -things to be different from runtime loading: - -<itemize> - -<item> Without changing the segment names, all segments take the default - names used by the standard linker configurations. This means that the - driver code is no longer contingous in memory, instead the code - segment is placed somewhere in between all other code segments, the - data segment is placed with all other data segments and so on. If the - driver doesn't do strange things this shouldn't be a problem. - -<item> With statically linked code, data and bss segments will get intialized - once (when the application is loaded), while a loadable driver will - get its initialization each time the driver is loaded into memory - (which may be more than once in the lifetime of a program). It depends - on the driver if this is a problem. Currently, most drivers supplied - with cc65 behave correctly when linked statically. - -</itemize> - - -<sect1>Additional requirements<p> - -All loadable drivers used by cc65 have a header and a jump table at the start -of the code segment. The header is needed to detect the driver (it may also -contain some data that is necessary to access the driver). The jump table is -used to access the functions in the driver code. - -When loading a driver at runtime, the load address of the driver is also the -address of the code segment, so the locations of the header and jump table are -known. However, when linking the driver statically, it is up to the programmer -to provide this information to the driver API. - -For this purpose, it is necessary to define a code segment label that can be -accessed from the outside later. Please note that the converter does currently -<em/not/ create such a label without being ordered to do so, even if the input -file is a cc65 module. - -To create such a label, use the <tt/--code-label/ option when calling the -converter. Be sure to begin the label with a leading underscore when accessing -it from C code. In your code, define an arbitrary variable with this name. Use -the address of this variable as the address of the code segment of the driver. -Be sure to never modify the variable which is in reality the start of your -driver! - - -<sect1>Example - Convert and link a graphics driver<p> - -As an example, here are some instructions to convert and use the c64-hi.tgi -graphics driver: - -First, convert the driver, generating a label named "_c64_hi" for the code -segment. Use the assembler to generate an object file from the assembler -output. - - <tscreen><verb> - co65 --code-label _c64_hi c64-hi.tgi - ca65 c64-hi.s - </verb></tscreen> - -Next, change your C code to declare a variable that is actually the address -of the driver: - - <tscreen><verb> - extern void c64_hi[]; - </verb></tscreen> - -Instead of loading and unloading the driver, change the code to install and -uninstall the driver, which will be already in memory after linking: - - <tscreen><verb> - /* Install the driver */ - tgi_install (c64_hi); - - ... - - /* Uninstall the driver */ - tgi_uninstall (); - </verb></tscreen> - -Don't forget to link the driver object file to your application, otherwise you -will get an "undefined external" error for the _c64_hi symbol. - - - - -<sect>Bugs/Feedback<p> - -If you have problems using the converter, if you find any bugs, or if you're -doing something interesting with the code, I would be glad to hear from you. -Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>Copyright<p> - -co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries -and/or sources the following conditions apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> - diff --git a/doc/coding.sgml b/doc/coding.sgml deleted file mode 100644 index 1aa454f12..000000000 --- a/doc/coding.sgml +++ /dev/null @@ -1,308 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>cc65 coding hints -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2000-12-03, 2009-09-01 - -<abstract> -How to generate the most effective code with cc65. -</abstract> - - - -<sect>Use prototypes<p> - -This will not only help to find errors between separate modules, it will also -generate better code, since the compiler must not assume that a variable sized -parameter list is in place and must not pass the argument count to the called -function. This will lead to shorter and faster code. - - - -<sect>Don't declare auto variables in nested function blocks<p> - -Variable declarations in nested blocks are usually a good thing. But with -cc65, there is a drawback: Since the compiler generates code in one pass, it -must create the variables on the stack each time the block is entered and -destroy them when the block is left. This causes a speed penalty and larger -code. - - - -<sect>Remember that the compiler does no high level optimizations<p> - -The compiler needs hints from you about the code to generate. It will try to -optimize the generated code, but follow the outline you gave in your C -program. So for example, when accessing indexed data structures, get a pointer -to the element and use this pointer instead of calculating the index again and -again. If you want to have your loops unrolled, or loop invariant code moved -outside the loop, you have to do that yourself. - - - -<sect>Longs are slow!<p> - -While long support is necessary for some things, it's really, really slow on -the 6502. Remember that any long variable will use 4 bytes of memory, and any -operation works on double the data compared to an int. - - - -<sect>Use unsigned types wherever possible<p> - -The 6502 CPU has no opcodes to handle signed values greater than 8 bit. So -sign extension, test of signedness etc. has to be done with extra code. As a -consequence, the code to handle signed operations is usually a bit larger and -slower than the same code for unsigned types. - - - -<sect>Use chars instead of ints if possible<p> - -While in arithmetic operations, chars are immidiately promoted to ints, they -are passed as chars in parameter lists and are accessed as chars in variables. -The code generated is usually not much smaller, but it is faster, since -accessing chars is faster. For several operations, the generated code may be -better if intermediate results that are known not to be larger than 8 bit are -casted to chars. - -You should especially use unsigned chars for loop control variables if the -loop is known not to execute more than 255 times. - - - -<sect>Make the size of your array elements one of 1, 2, 4, 8<p> - -When indexing into an array, the compiler has to calculate the byte offset -into the array, which is the index multiplied by the size of one element. When -doing the multiplication, the compiler will do a strength reduction, that is, -replace the multiplication by a shift if possible. For the values 2, 4 and 8, -there are even more specialized subroutines available. So, array access is -fastest when using one of these sizes. - - - -<sect>Expressions are evaluated from left to right<p> - -Since cc65 is not building an explicit expression tree when parsing an -expression, constant subexpressions may not be detected and optimized properly -if you don't help. Look at this example: - -<tscreen><verb> - #define OFFS 4 - int i; - i = i + OFFS + 3; -</verb></tscreen> - -The expression is parsed from left to right, that means, the compiler sees 'i', -and puts it contents into the secondary register. Next is OFFS, which is -constant. The compiler emits code to add a constant to the secondary register. -Same thing again for the constant 3. So the code produced contains a fetch -of 'i', two additions of constants, and a store (into 'i'). Unfortunately, the -compiler does not see, that "OFFS + 3" is a constant for itself, since it does -its evaluation from left to right. There are some ways to help the compiler -to recognize expression like this: - -<enum> - -<item>Write "i = OFFS + 3 + i;". Since the first and second operand are -constant, the compiler will evaluate them at compile time reducing the code to -a fetch, one addition (secondary + constant) and one store. - -<item>Write "i = i + (OFFS + 3)". When seeing the opening parenthesis, the -compiler will start a new expression evaluation for the stuff in the braces, -and since all operands in the subexpression are constant, it will detect this -and reduce the code to one fetch, one addition and one store. - -</enum> - - -<sect>Use the preincrement and predecrement operators<p> - -The compiler is not always smart enough to figure out, if the rvalue of an -increment is used or not. So it has to save and restore that value when -producing code for the postincrement and postdecrement operators, even if this -value is never used. To avoid the additional overhead, use the preincrement -and predecrement operators if you don't need the resulting value. That means, -use - -<tscreen><verb> - ... - ++i; - ... -</verb></tscreen> - - instead of - -<tscreen><verb> - ... - i++; - ... -</verb></tscreen> - - - -<sect>Use constants to access absolute memory locations<p> - -The compiler produces optimized code, if the value of a pointer is a constant. -So, to access direct memory locations, use - -<tscreen><verb> - #define VDC_STATUS 0xD601 - *(char*)VDC_STATUS = 0x01; -</verb></tscreen> - -That will be translated to - -<tscreen><verb> - lda #$01 - sta $D601 -</verb></tscreen> - -The constant value detection works also for struct pointers and arrays, if the -subscript is a constant. So - -<tscreen><verb> - #define VDC ((unsigned char*)0xD600) - #define STATUS 0x01 - VDC[STATUS] = 0x01; -</verb></tscreen> - -will also work. - -If you first load the constant into a variable and use that variable to access -an absolute memory location, the generated code will be much slower, since the -compiler does not know anything about the contents of the variable. - - - -<sect>Use initialized local variables<p> - -Initialization of local variables when declaring them gives shorter and faster -code. So, use - -<tscreen><verb> - int i = 1; -</verb></tscreen> - -instead of - -<tscreen><verb> - int i; - i = 1; -</verb></tscreen> - -But beware: To maximize your savings, don't mix uninitialized and initialized -variables. Create one block of initialized variables and one of uniniitalized -ones. The reason for this is, that the compiler will sum up the space needed -for uninitialized variables as long as possible, and then allocate the space -once for all these variables. If you mix uninitialized and initialized -variables, you force the compiler to allocate space for the uninitialized -variables each time, it parses an initialized one. So do this: - -<tscreen><verb> - int i, j; - int a = 3; - int b = 0; -</verb></tscreen> - -instead of - -<tscreen><verb> - int i; - int a = 3; - int j; - int b = 0; -</verb></tscreen> - -The latter will work, but will create larger and slower code. - - - -<sect>Use the array operator [] even for pointers<p> - -When addressing an array via a pointer, don't use the plus and dereference -operators, but the array operator. This will generate better code in some -common cases. - -Don't use - -<tscreen><verb> - char* a; - char b, c; - char b = *(a + c); -</verb></tscreen> - -Use - -<tscreen><verb> - char* a; - char b, c; - char b = a[c]; -</verb></tscreen> - -instead. - - - -<sect>Use register variables with care<p> - -Register variables may give faster and shorter code, but they do also have an -overhead. Register variables are actually zero page locations, so using them -saves roughly one cycle per access. The calling routine may also use register -variables, so the old values have to be saved on function entry and restored -on exit. Saving an d restoring has an overhead of about 70 cycles per 2 byte -variable. It is easy to see, that - apart from the additional code that is -needed to save and restore the values - you need to make heavy use of a -variable to justify the overhead. - -As a general rule: Use register variables only for pointers that are -dereferenced several times in your function, or for heavily used induction -variables in a loop (with several 100 accesses). - -When declaring register variables, try to keep them together, because this -will allow the compiler to save and restore the old values in one chunk, and -not in several. - -And remember: Register variables must be enabled with <tt/-r/ or <tt/-Or/. - - - -<sect>Decimal constants greater than 0x7FFF are actually long ints<p> - -The language rules for constant numeric values specify that decimal constants -without a type suffix that are not in integer range must be of type long int -or unsigned long int. So a simple constant like 40000 is of type long int! -This is often unexpected and may cause an expression to be evaluated with 32 -bits. While in many cases the compiler takes care about it, in some places it -can't. So be careful when you get a warning like - -<tscreen><verb> - test.c(7): Warning: Constant is long -</verb></tscreen> - -Use the <tt/U/, <tt/L/ or <tt/UL/ suffixes to tell the compiler the desired -type of a numeric constant. - - - -<sect>Access to parameters in variadic functions is expensive<p> - -Since cc65 has the "wrong" calling order, the location of the fixed parameters -in a variadic function (a function with a variable parameter list) depends on -the number and size of variable arguments passed. Since this number and size -is unknown at compile time, the compiler will generate code to calculate the -location on the stack when needed. - -Because of this additional code, accessing the fixed parameters in a variadic -function is much more expensive than access to parameters in a "normal" -function. Unfortunately, this additional code is also invisible to the -programmer, so it is easy to forget. - -As a rule of thumb, if you access such a parameter more than once, you should -think about copying it into a normal variable and using this variable instead. - - -</article> - diff --git a/doc/compile.txt b/doc/compile.txt deleted file mode 100644 index 5061d1ed2..000000000 --- a/doc/compile.txt +++ /dev/null @@ -1,316 +0,0 @@ - - -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. - - - diff --git a/doc/customizing.sgml b/doc/customizing.sgml deleted file mode 100644 index 23cf8c5e8..000000000 --- a/doc/customizing.sgml +++ /dev/null @@ -1,730 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>Defining a Custom cc65 Target -<author>Bruce Reidenbach -<date>2010-02-22 - -<abstract> -This section provides step-by-step instructions on how to use the cc65 -toolset for a custom hardware platform (a target system not currently -supported by the cc65 library set). -</abstract> - -<!-- Table of contents --> - -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -The cc65 toolset provides a set of pre-defined libraries that allow the -user to target the executable image to a variety of hardware platforms. -In addition, the user can create a customized environment so that the -executable can be targeted to a custom platform. The following -instructions provide step-by-step instructions on how to customize the -toolset for a target that is not supported by the standard cc65 -installation. - -The platform used in this example is a Xilinx Field Programmable Gate -Array (FPGA) with an embedded 65C02 core. The processor core supports -the additional opcodes/addressing modes of the 65SC02, along with the -STP and WAI instructions. These instructions will create a set of files -to create a custom target, named SBC, for <bf>S</bf>ingle <bf>B</bf>oard -<bf>C</bf>omputer. - -<sect>System Memory Map Definition<p> - -The targeted system uses block RAM contained on the XILINX FPGA for the -system memory (both RAM and ROM). The block RAMs are available in -various aspect ratios, and they will be used in this system as 2K*8 -devices. There will be two RAMs used for data storage, starting at -location $0000 and growing upwards. There will be one ROM (realized as -initialized RAM) used code storage, starting at location $FFFF and -growing downwards. - -The cc65 toolset requires a memory configuration file to define the -memory that is available to the cc65 run-time environment, which is -defined as follows: - -<tscreen><code> -MEMORY { - ZP: start = $0, size = $100, type = rw, define = yes; - RAM: start = $200, size = $0E00, define = yes; - ROM: start = $F800, size = $0800, file = %O; -} -</code></tscreen> - -ZP defines the available zero page locations, which in this case starts -at $0 and has a length of $100. Keep in mind that certain systems may -require access to some zero page locations, so the starting address may -need to be adjusted accordingly to prevent cc65 from attempting to reuse -those locations. Also, at a minimum, the cc65 run-time environment uses -26 zero page locations, so the smallest zero page size that can be -specified is $1A. The usable RAM memory area begins after the 6502 -stack storage in page 1, so it is defined as starting at location $200 -and filling the remaining 4K of space (4096 - 2 * -256 = 3584 = $0E00). The 2K of ROM space begins at -address $F800 and goes to $FFFF (size = $0800). - -Next, the memory segments within the memory devices need to be defined. -A standard segment definition is used, with one notable exception. The -interrupt and reset vector locations need to be defined at locations -$FFFA through $FFFF. A special segment named VECTORS is defined that -resides at these locations. Later, the interrupt vector map will be -created and placed in the VECTORS segment, and the linker will put these -vectors at the proper memory locations. The segment definition is: - -<tscreen><code> -SEGMENTS { - ZEROPAGE: load = ZP, type = zp, define = yes; - DATA: load = ROM, type = rw, define = yes, run = RAM; - BSS: load = RAM, type = bss, define = yes; - HEAP: load = RAM, type = bss, optional = yes; - STARTUP: load = ROM, type = ro; - INIT: load = ROM, type = ro, optional = yes; - CODE: load = ROM, type = ro; - RODATA: load = ROM, type = ro; - VECTORS: load = ROM, type = ro, start = $FFFA; -} -</code></tscreen> - -The meaning of each of these segments is as follows. - -<p><tt> ZEROPAGE: </tt>Data in page 0, defined by ZP as starting at $0 with length $100 -<p><tt> DATA: </tt>Initialized data that can be modified by the program, stored in RAM -<p><tt> BSS: </tt>Uninitialized data stored in RAM (used for variable storage) -<p><tt> HEAP: </tt>Uninitialized C-level heap storage in RAM, optional -<p><tt> STARTUP: </tt>The program initialization code, stored in ROM -<p><tt> INIT: </tt>The code needed to initialize the system, stored in ROM -<p><tt> CODE: </tt>The program code, stored in ROM -<p><tt> RODATA: </tt>Initialized data that cannot be modified by the program, stored in ROM -<p><tt> VECTORS: </tt>The interrupt vector table, stored in ROM at location $FFFA - -A note about initialized data: any variables that require an initial -value, such as external (global) variables, require that the initial -values be stored in the ROM code image. However, variables stored in -ROM cannot change; therefore the data must be moved into variables that -are located in RAM. Specifying <tt>run = RAM</tt> as part of -the DATA segment definition will indicate that those variables will -require their initialization value to be copied via a call to the -<tt>copydata</tt> routine in the startup assembly code. In addition, -there are system level variables that will need to be initialized as -well, especially if the heap segment is used via a C-level call to -<tt>malloc ()</tt>. - -The final section of the definition file contains the data constructors -and destructors used for system startup. In addition, if the heap is -used, the maximum C-level stack size needs to be defined in order for -the system to be able to reliably allocate blocks of memory. The stack -size selection must be greater than the maximum amount of storage -required to run the program, keeping in mind that the C-level subroutine -call stack and all local variables are stored in this stack. The -<tt>FEATURES</tt> section defines the required constructor/destructor -attributes and the <tt>SYMBOLS</tt> section defines the stack size. The -constructors will be run via a call to <tt>initlib</tt> in the startup -assembly code and the destructors will be run via an assembly language -call to <tt>donelib</tt> during program termination. - -<tscreen><code> -FEATURES { - CONDES: segment = STARTUP, - type = constructor, - label = __CONSTRUCTOR_TABLE__, - count = __CONSTRUCTOR_COUNT__; - CONDES: segment = STARTUP, - type = destructor, - label = __DESTRUCTOR_TABLE__, - count = __DESTRUCTOR_COUNT__; -} - -SYMBOLS { - # Define the stack size for the application - __STACKSIZE__: value = $0200, weak = yes; -} -</code></tscreen> - -These definitions are placed in a file named "sbc.cfg" -and are referred to during the ld65 linker stage. - -<sect>Startup Code Definition<p> - -In the cc65 toolset, a startup routine must be defined that is executed -when the CPU is reset. This startup code is marked with the STARTUP -segment name, which was defined in the system configuration file as -being in read only memory. The standard convention used in the -predefined libraries is that this code is resident in the crt0 module. -For this custom system, all that needs to be done is to perform a little -bit of 6502 housekeeping, set up the C-level stack pointer, initialize -the memory storage, and call the C-level routine <tt>main ()</tt>. -The following code was used for the crt0 module, defined in the file -"crt0.s": - -<tscreen><code> -; --------------------------------------------------------------------------- -; crt0.s -; --------------------------------------------------------------------------- -; -; Startup code for cc65 (Single Board Computer version) - -.export _init, _exit -.import _main - -.export __STARTUP__ : absolute = 1 ; Mark as startup -.import __RAM_START__, __RAM_SIZE__ ; Linker generated - -.import copydata, zerobss, initlib, donelib - -.include "zeropage.inc" - -; --------------------------------------------------------------------------- -; Place the startup code in a special segment - -.segment "STARTUP" - -; --------------------------------------------------------------------------- -; A little light 6502 housekeeping - -_init: LDX #$FF ; Initialize stack pointer to $01FF - TXS - CLD ; Clear decimal mode - -; --------------------------------------------------------------------------- -; Set cc65 argument stack pointer - - LDA #<(__RAM_START__ + __RAM_SIZE__) - STA sp - LDA #>(__RAM_START__ + __RAM_SIZE__) - STA sp+1 - -; --------------------------------------------------------------------------- -; Initialize memory storage - - JSR zerobss ; Clear BSS segment - JSR copydata ; Initialize DATA segment - JSR initlib ; Run constructors - -; --------------------------------------------------------------------------- -; Call main() - - JSR _main - -; --------------------------------------------------------------------------- -; Back from main (this is also the _exit entry): force a software break - -_exit: JSR donelib ; Run destructors - BRK -</code></tscreen> - -The following discussion explains the purpose of several important -assembler level directives in this file. - -<tscreen><verb> -.export _init, _exit -</verb></tscreen> - -This line instructs the assembler that the symbols <tt>_init</tt> and -<tt>_exit</tt> are to be accessible from other modules. In this -example, <tt>_init</tt> is the location that the CPU should jump to when -reset, and <tt>_exit</tt> is the location that will be called when the -program is finished. - -<tscreen><verb> -.import _main -</verb></tscreen> - -This line instructs the assembler to import the symbol <tt>_main</tt> -from another module. cc65 names all C-level routines as -{underscore}{name} in assembler, thus the <tt>main ()</tt> routine -in C is named <tt>_main</tt> in the assembler. This is how the startup -code will link to the C-level code. - -<tscreen><verb> -.export __STARTUP__ : absolute = 1 ; Mark as startup -</verb></tscreen> - -This line marks this code as startup code (code that is executed when -the processor is reset), which will then be automatically linked into -the executable code. - -<tscreen><verb> -.import __RAM_START__, __RAM_SIZE__ ; Linker generated -</verb></tscreen> - -This line imports the RAM starting address and RAM size constants, which -are used to initialize the cc65 C-level argument stack pointer. - -<tscreen><verb> -.segment "STARTUP" -</verb></tscreen> - -This line instructs the assembler that the code is to be placed in the -STARTUP segment of memory. - -<tscreen><verb> - JSR zerobss ; Clear BSS segment - JSR copydata ; Initialize DATA segment - JSR initlib ; Run constructors -</verb></tscreen> - -These three lines initialize the external (global) and system -variables. The first line sets the BSS segment -- the memory locations -used for external variables -- to 0. The second line copies the -initialization value stored in ROM to the RAM locations used for -initialized external variables. The last line runs the constructors -that are used to initialize the system run-time variables. - -<tscreen><verb> - JSR _main -</verb></tscreen> - -This is the actual call to the C-level <tt>main ()</tt> routine, -which is called after the startup code completes. - -<tscreen><verb> -_exit: JSR donelib ; Run destructors - BRK -</verb></tscreen> - -This is the code that will be executed when <tt>main ()</tt> -terminates. The first thing that must be done is run the destructors -via a call to <tt>donelib</tt>. Then the program can terminate. In -this example, the program is expected to run forever. Therefore, there -needs to be a way of indicating when something has gone wrong and the -system needs to be shut down, requiring a restart only by a hard reset. -The BRK instruction will be used to indicate a software fault. This is -advantageous because cc65 uses the BRK instruction as the fill byte in -the final binary code. In addition, the hardware has been designed to -force the data lines to $00 for all illegal memory accesses, thereby -also forcing a BRK instruction into the CPU. - -<sect>Custom Run-Time Library Creation<p> - -The next step in customizing the cc65 toolset is creating a run-time -library for the targeted hardware. The easiest way to do this is to -modify a standard library from the cc65 distribution. In this example, -there is no console I/O, mouse, joystick, etc. in the system, so it is -most appropriate to use the simplest library as the base, which is for -the Watara Supervision and is named "supervision.lib" in the -lib directory of the distribution. - -The only modification required is to replace the <tt>crt0</tt> module in -the supervision.lib library with custom startup code. This is simply -done by first copying the library and giving it a new name, compiling -the startup code with ca65, and finally using the ar65 archiver to -replace the module in the new library. The steps are shown below: - -<tscreen><verb> -$ copy "C:\Program Files\cc65\lib\supervision.lib" sbc.lib -$ ca65 crt0.s -$ ar65 a sbc.lib crt0.o -</verb></tscreen> - -<sect>Interrupt Service Routine Definition<p> - -For this system, the CPU is put into a wait condition prior to allowing -interrupt processing. Therefore, the interrupt service routine is very -simple: return from all valid interrupts. However, as mentioned -before, the BRK instruction is used to indicate a software fault, which -will call the same interrupt service routine as the maskable interrupt -signal IRQ. The interrupt service routine must be able to tell the -difference between the two, and act appropriately. - -The interrupt service routine shown below includes code to detect when a -BRK instruction has occurred and stops the CPU from further processing. -The interrupt service routine is in a file named -"interrupt.s". - -<tscreen><code> -; --------------------------------------------------------------------------- -; interrupt.s -; --------------------------------------------------------------------------- -; -; Interrupt handler. -; -; Checks for a BRK instruction and returns from all valid interrupts. - -.import _stop -.export _irq_int, _nmi_int - -.segment "CODE" - -.PC02 ; Force 65C02 assembly mode - -; --------------------------------------------------------------------------- -; Non-maskable interrupt (NMI) service routine - -_nmi_int: RTI ; Return from all NMI interrupts - -; --------------------------------------------------------------------------- -; Maskable interrupt (IRQ) service routine - -_irq_int: PHX ; Save X register contents to stack - TSX ; Transfer stack pointer to X - PHA ; Save accumulator contents to stack - INX ; Increment X so it points to the status - INX ; register value saved on the stack - LDA $100,X ; Load status register contents - AND #$10 ; Isolate B status bit - BNE break ; If B = 1, BRK detected - -; --------------------------------------------------------------------------- -; IRQ detected, return - -irq: PLA ; Restore accumulator contents - PLX ; Restore X register contents - RTI ; Return from all IRQ interrupts - -; --------------------------------------------------------------------------- -; BRK detected, stop - -break: JMP _stop ; If BRK is detected, something very bad - ; has happened, so stop running -</code></tscreen> - -The following discussion explains the purpose of several important -assembler level directives in this file. - -<tscreen><verb> -.import _stop -</verb></tscreen> - -This line instructs the assembler to import the symbol <tt>_stop</tt> -from another module. This routine will be called if a BRK instruction -is encountered, signaling a software fault. - -<tscreen><verb> -.export _irq_int, _nmi_int -</verb></tscreen> - -This line instructs the assembler that the symbols <tt>_irq_int</tt> and -<tt>_nmi_int</tt> are to be accessible from other modules. In this -example, the address of these symbols will be placed in the interrupt -vector table. - -<tscreen><verb> -.segment "CODE" -</verb></tscreen> - -This line instructs the assembler that the code is to be placed in the -CODE segment of memory. Note that because there are 65C02 mnemonics in -the assembly code, the assembler is forced to use the 65C02 instruction -set with the <tt>.PC02</tt> directive. - -The final step is to define the interrupt vector memory locations. -Recall that a segment named VECTORS was defined in the memory -configuration file, which started at location $FFFA. The addresses of -the interrupt service routines from "interrupt.s" along with -the address for the initialization code in crt0 are defined in a file -named "vectors.s". Note that these vectors will be placed in -memory in their proper little-endian format as: - -<p><tt> $FFFA - $FFFB:</tt> NMI interrupt vector (low byte, high byte) -<p><tt> $FFFC - $FFFD:</tt> Reset vector (low byte, high byte) -<p><tt> $FFFE - $FFFF:</tt> IRQ/BRK interrupt vector (low byte, high byte) - -using the <tt>.addr</tt> assembler directive. The contents of the file are: - -<tscreen><code> -; --------------------------------------------------------------------------- -; vectors.s -; --------------------------------------------------------------------------- -; -; Defines the interrupt vector table. - -.import _init -.import _nmi_int, _irq_int - -.segment "VECTORS" - -.addr _nmi_int ; NMI vector -.addr _init ; Reset vector -.addr _irq_int ; IRQ/BRK vector -</code></tscreen> - -The cc65 toolset will replace the address symbols defined here with the -actual addresses of the routines during the link process. - -<sect>Adding Custom Instructions<p> - -The cc65 instruction set only supports the WAI (Wait for Interrupt) and -STP (Stop) instructions when used with the 65816 CPU (accessed via the ---cpu command line option of the ca65 macro assembler). The 65C02 core -used in this example supports these two instructions, and in fact the -system benefits from the use of both the WAI and STP instructions. - -In order to use the WAI instruction in this case, a C routine named -"wait" was created that consists of the WAI opcode followed by -a subroutine return. It was convenient in this example to put the IRQ -interrupt enable in this subroutine as well, since interrupts should -only be enabled when the code is in this wait condition. - -For both the WAI and STP instructions, the assembler is -"fooled" into placing those opcodes into memory by inserting a -single byte of data that just happens to be the opcode for those -instructions. The assembly code routines are placed in a file, named -"wait.s", which is shown below: - -<tscreen><code> -; --------------------------------------------------------------------------- -; wait.s -; --------------------------------------------------------------------------- -; -; Wait for interrupt and return - -.export _wait, _stop - -; --------------------------------------------------------------------------- -; Wait for interrupt: Forces the assembler to emit a WAI opcode ($CB) -; --------------------------------------------------------------------------- - -.segment "CODE" - -.proc _wait: near - - CLI ; Enable interrupts -.byte $CB ; Inserts a WAI opcode - RTS ; Return to caller - -.endproc - -; --------------------------------------------------------------------------- -; Stop: Forces the assembler to emit a STP opcode ($DB) -; --------------------------------------------------------------------------- - -.proc _stop: near - -.byte $DB ; Inserts a STP opcode - -.endproc -</code></tscreen> - -The label <tt>_wait</tt>, when exported, can be called by using the -<tt>wait ()</tt> subroutine call in C. The section is marked as -code so that it will be stored in read-only memory, and the procedure is -tagged for 16-bit absolute addressing via the "near" -modifier. Similarly, the <tt>_stop</tt> routine can be called from -within the C-level code via a call to <tt>stop ()</tt>. In -addition, the routine can be called from assembly code by calling -<tt>_stop</tt> (as was done in the interrupt service routine). - -<sect>Hardware Drivers<p> - -Oftentimes, it can be advantageous to create small application helpers -in assembly language to decrease codespace and increase execution speed -of the overall program. An example of this would be the transfer of -characters to a FIFO (<bf>F</bf>irst-<bf>I</bf>n, -<bf>F</bf>irst-<bf>O</bf>ut) storage buffer for transmission over a -serial port. This simple action could be performed by an assembly -language driver which would execute much quicker than coding it in C. -The following discussion outlines a method of interfacing a C program -with an assembly language subroutine. - -The first step in creating the assembly language code for the driver is -to determine how to pass the C arguments to the assembly language -routine. The cc65 toolset allows the user to specify whether the data -is passed to a subroutine via the stack or by the processor registers by -using the <tt>__fastcall__</tt> function declaration (note that there -are two underscore characters in front of and two behind the -<tt>fastcall</tt> declaration). When <tt>__fastcall__</tt> is -specified, the rightmost argument in the function call is passed to the -subroutine using the 6502 registers instead of the stack. Note that if -there is only one argument in the function call, the execution overhead -required by the stack interface routines is completely avoided. - -Without <tt>__fastcall__</tt>, the argument is loaded in the A and X -registers and then pushed onto the stack via a call to <tt>pushax</tt>. -The first thing the subroutine does is retrieve the argument from the -stack via a call to <tt>ldax0sp</tt>, which copies the values into the A -and X. When the subroutine is finished, the values on the stack must be -popped off and discarded via a jump to <tt>incsp2</tt>, which includes -the RTS subroutine return command. This is shown in the following code -sample. - -Calling sequence: - -<tscreen><verb> - lda #<(L0001) ; Load A with the high order byte - ldx #>(L0001) ; Load X with the low order byte - jsr pushax ; Push A and X onto the stack - jsr _foo ; Call foo, i.e., foo (arg) -</verb></tscreen> - -Subroutine code: - -<tscreen><verb> -_foo: jsr ldax0sp ; Retrieve A and X from the stack - sta ptr ; Store A in ptr - stx ptr+1 ; Store X in ptr+1 - ... ; (more subroutine code goes here) - jmp incsp2 ; Pop A and X from the stack (includes return) -</verb></tscreen> - -If <tt>__fastcall__</tt> is specified, the argument is loaded into the A -and X registers as before, but the subroutine is then called -immediately. The subroutine does not need to retrieve the argument -since the value is already available in the A and X registers. -Furthermore, the subroutine can be terminated with an RTS statement -since there is no stack cleanup which needs to be performed. This is -shown in the following code sample. - -Calling sequence: - -<tscreen><verb> - lda #<(L0001) ; Load A with the high order byte - ldx #>(L0001) ; Load X with the low order byte - jsr _foo ; Call foo, i.e., foo (arg) -</verb></tscreen> - -Subroutine code: - -<tscreen><verb> -_foo: sta ptr ; Store A in ptr - stx ptr+1 ; Store X in ptr+1 - ... ; (more subroutine code goes here) - rts ; Return from subroutine -</verb></tscreen> - -The hardware driver in this example writes a string of character data to -a hardware FIFO located at memory location $1000. Each character is -read and is compared to the C string termination value ($00), which will -terminate the loop. All other character data is written to the FIFO. -For convenience, a carriage return/line feed sequence is automatically -appended to the serial stream. The driver defines a local pointer -variable which is stored in the zero page memory space in order to allow -for retrieval of each character in the string via the indirect indexed -addressing mode. - -The assembly language routine is stored in a file names -"rs232_tx.s" and is shown below: - -<tscreen><code> -; --------------------------------------------------------------------------- -; rs232_tx.s -; --------------------------------------------------------------------------- -; -; Write a string to the transmit UART FIFO - -.export _rs232_tx -.exportzp _rs232_data: near - -.define TX_FIFO $1000 ; Transmit FIFO memory location - -.zeropage - -_rs232_data: .res 2, $00 ; Reserve a local zero page pointer - -.segment "CODE" - -.proc _rs232_tx: near - -; --------------------------------------------------------------------------- -; Store pointer to zero page memory and load first character - - sta _rs232_data ; Set zero page pointer to string address - stx _rs232_data+1 ; (pointer passed in via the A/X registers) - ldy #00 ; Initialize Y to 0 - lda (_rs232_data) ; Load first character - -; --------------------------------------------------------------------------- -; Main loop: read data and store to FIFO until \0 is encountered - -loop: sta TX_FIFO ; Loop: Store character in FIFO - iny ; Increment Y index - lda (_rs232_data),y ; Get next character - bne loop ; If character == 0, exit loop - -; --------------------------------------------------------------------------- -; Append CR/LF to output stream and return - - lda #$0D ; Store CR - sta TX_FIFO - lda #$0A ; Store LF - sta TX_FIFO - rts ; Return - -.endproc -</code></tscreen> - -<sect>Hello World! Example<p> - -The following short example demonstrates programming in C using the cc65 -toolset with a custom run-time environment. In this example, a Xilinx -FPGA contains a UART which is connected to a 65c02 processor with FIFO -(<bf>F</bf>irst-<bf>I</bf>n, <bf>F</bf>irst-<bf>O</bf>ut) storage to -buffer the data. The C program will wait for an interrupt generated by -the receive UART and then respond by transmitting the string "Hello -World! " every time a question mark character is received via a -call to the hardware driver <tt>rs232_tx ()</tt>. The driver -prototype uses the <tt>__fastcall__</tt> extension to indicate that the -driver does not use the stack. The FIFO data interface is at address -$1000 and is defined as the symbolic constant <tt>FIFO_DATA</tt>. -Writing to <tt>FIFO_DATA</tt> transfers a byte of data into the transmit -FIFO for subsequent transmission over the serial interface. Reading -from <tt>FIFO_DATA</tt> transfers a byte of previously received data out -of the receive FIFO. The FIFO status data is at address $1001 and is -defined as the symbolic constant <tt>FIFO_STATUS</tt>. For convenience, -the symbolic constants <tt>TX_FIFO_FULL</tt> (which isolates bit 0 of -the register) and <tt>RX_FIFO_EMPTY</tt> (which isolates bit 1 of the -register) have been defined to read the FIFO status. - -The following C code is saved in the file "main.c". As this -example demonstrates, the run-time environment has been set up such that -all of the behind-the-scene work is transparent to the user. - -<tscreen><code> -#define FIFO_DATA (*(unsigned char *) 0x1000) -#define FIFO_STATUS (*(unsigned char *) 0x1001) - -#define TX_FIFO_FULL (FIFO_STATUS & 0x01) -#define RX_FIFO_EMPTY (FIFO_STATUS & 0x02) - -extern void wait (); -extern void __fastcall__ rs232_tx (char *str); - -int main () { - while (1) { // Run forever - wait (); // Wait for an RX FIFO interrupt - - while (RX_FIFO_EMPTY == 0) { // While the RX FIFO is not empty - if (FIFO_DATA == '?') { // Does the RX character = '?' - rs232_tx ("Hello World!"); // Transmit "Hello World!" - } // Discard any other RX characters - } - } - - return (0); // We should never get here! -} -</code></tscreen> - -<sect>Putting It All Together<p> - -The following commands will create a ROM image named "a.out" -that can be used as the initialization data for the Xilinx Block RAM -used for code storage: - -<tscreen><verb> -$ cc65 -t none -O --cpu 65sc02 main.c -$ ca65 --cpu 65sc02 main.s -$ ca65 --cpu 65sc02 rs232_tx.s -$ ca65 --cpu 65sc02 interrupt.s -$ ca65 --cpu 65sc02 vectors.s -$ ca65 --cpu 65sc02 wait.s -$ ld65 -C sbc.cfg -m main.map interrupt.o vectors.o wait.o rs232_tx.o - main.o sbc.lib -</verb></tscreen> - -During the C-level code compilation phase (<tt>cc65</tt>), assumptions -about the target system are disabled via the <tt>-t none</tt> command -line option. During the object module linker phase (<tt>ld65</tt>), the -target customization is enabled via inclusion of the <tt>sbc.lib</tt> -file and the selection of the configuration file via the <tt>-C -sbc.cfg</tt> command line option. - -The 65C02 core used most closely matches the cc65 toolset processor -named 65SC02 (the 65C02 extensions without the bit manipulation -instructions), so all the commands specify the use of that processor via -the <tt>--cpu 65sc02</tt> option. - -</article> diff --git a/doc/da65.sgml b/doc/da65.sgml deleted file mode 100644 index 58d031eff..000000000 --- a/doc/da65.sgml +++ /dev/null @@ -1,694 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>da65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-08-08 - -<abstract> -da65 is a 6502/65C02 disassembler that is able to read user supplied -information about its input data for better results. The output is ready for -feeding into ca65, the macro assembler supplied with the cc65 C compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with -the cc65 C compiler and generates output that is suitable for the ca65 -macro assembler. - -Besides generating output for ca65, one of the design goals was that the user -is able to feed additional information about the code into the disassembler -for improved results. This information may include the location and size of -tables, and their format. - -One nice advantage of this concept is that disassembly of copyrighted binaries -may be handled without problems: One can just pass the information file for -disassembling the binary, so everyone with a legal copy of the binary can -generate a nicely formatted disassembly with readable labels and other -information. - - -<sect>Usage<p> - - -<sect1>Command line option overview<p> - -The assembler accepts the following options: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: da65 [options] [inputfile] -Short options: - -g Add debug info to object file - -h Help (this text) - -i name Specify an info file - -o name Name the output file - -v Increase verbosity - -F Add formfeeds to the output - -S addr Set the start/load address - -V Print the disassembler version - -Long options: - --argument-column n Specify argument start column - --comment-column n Specify comment start column - --comments n Set the comment level for the output - --cpu type Set cpu type - --debug-info Add debug info to object file - --formfeeds Add formfeeds to the output - --help Help (this text) - --hexoffs Use hexadecimal label offsets - --info name Specify an info file - --label-break n Add newline if label exceeds length n - --mnemonic-column n Specify mnemonic start column - --pagelength n Set the page length for the listing - --start-addr addr Set the start/load address - --text-column n Specify text start column - --verbose Increase verbosity - --version Print the disassembler version ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<p> - -Here is a description of all the command line options: - -<descrip> - - <label id="option--argument-column"> - <tag><tt>--argument-column n</tt></tag> - - Specifies the column where the argument for a mnemonic or pseudo instruction - starts. - - - <label id="option--comment-column"> - <tag><tt>--comment-column n</tt></tag> - - Specifies the column where the comment for an instruction starts. - - - <label id="option--comments"> - <tag><tt>--comments n</tt></tag> - - Set the comment level for the output. Valid arguments are 0..4. Greater - values will increase the level of additional information written to the - output file in form of comments. - - - <label id="option--cpu"> - <tag><tt>--cpu type</tt></tag> - - Set the CPU type. The option takes a parameter, which may be one of - - 6502, 6502x, 65sc02, 65c02, huc6280 - - 6502x is the NMOS 6502 with illegal opcodes. huc6280 is the CPU of the PC - engine. Support for the 65816 is currently not available. - - - <label id="option--formfeeds"> - <tag><tt>-F, --formfeeds</tt></tag> - - Add formfeeds to the generated output. This feature is useful together - with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option. - If <tt/--formfeeds/ is given, a formfeed is added to the output after each - page. - - - <tag><tt>-g, --debug-info</tt></tag> - - This option adds the <tt/.DEBUGINFO/ command to the output file, so the - assembler will generate debug information when reassembling the generated - output. - - - <tag><tt>-h, --help</tt></tag> - - Print the short option summary shown above. - - - <label id="option--hexoffs"> - <tag><tt>--hexoffs</tt></tag> - - Output label offsets in hexadecimal instead of decimal notation. - - - <label id="option--info"> - <tag><tt>-i name, --info name</tt></tag> - - Specify an info file. The info file contains global options that may - override or replace command line options plus informations about the code - that has to be disassembled. See the separate section <ref id="infofile" - name="Info File Format">. - - - <label id="option-o"> - <tag><tt>-o name</tt></tag> - - Specify a name for an output file. The default is to use <tt/stdout/, so - without this switch or the corresponding <ref id="global-options" - name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>, - the output will go to the terminal. - - - <label id="option--label-break"> - <tag><tt>--label-break n</tt></tag> - - Adds a newline if the length of a label exceeds the given length. - Note: If the label would run into the code in the mid column, a - linefeed is always inserted regardless of this setting. - - This option overrides the <ref id="global-options" name="global option"> - <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>. - - - <label id="option--mnemonic-column"> - <tag><tt>--mnemonic-column n</tt></tag> - - Specifies the column where a mnemonic or pseudo instrcuction is output. - - - <label id="option--pagelength"> - <tag><tt>--pagelength n</tt></tag> - - Sets the length of a listing page in lines. After this number of lines, a - new page header is generated. If the <tt><ref id="option--formfeeds" - name="--formfeeds"></tt> is also given, a formfeed is inserted before - generating the page header. - - A value of zero for the page length will disable paging of the output. - - - <label id="option--start-addr"> - <tag><tt>-S addr, --start-addr addr</tt></tag> - - Specify the start/load address of the binary code that is going to be - disassembled. The given address is interpreted as an octal value if - preceded with a '0' digit, as a hexadecimal value if preceded - with '0x', '0X', or '$', and as a decimal value in all other cases. If no - start address is specified, $10000 minus the size of the input file is used. - - - <label id="option--text-column"> - <tag><tt>--text-column n</tt></tag> - - Specifies the column where additional text is output. This additional text - consists of the bytes encoded in this line in text representation. - - - <tag><tt>-v, --verbose</tt></tag> - - Increase the disassembler verbosity. Usually only needed for debugging - purposes. You may use this option more than one time for even more - verbose output. - - - <tag><tt>-V, --version</tt></tag> - - Print the version number of the assembler. If you send any suggestions - or bugfixes, please include the version number. - -</descrip> -<p> - - -<sect>Detailed workings<p> - -<sect1>Supported CPUs<p> - -The default (no CPU given on the command line or in the <tt/GLOBAL/ section of -the info file) is the 6502 CPU. The disassembler knows all "official" opcodes -for this CPU. Invalid opcodes are translated into <tt/.byte/ commands. - -With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the -disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The -latter understands the same opcodes as the former, plus 16 additional bit -manipulation and bit test-and-branch commands. - -While there is some code for the 65816 in the sources, it is currently -unsupported. - - -<sect1>Attribute map<p> - -The disassembler works by creating an attribute map for the whole address -space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an -external info file (if given) is read. Disassembly is done in several passes. -In all passes with the exception of the last one, information about the -disassembled code is gathered and added to the symbol and attribute maps. The -last pass generates output using the information from the maps. - -<sect1>Labels<p> - -Some instructions may generate labels in the first pass, while most other -instructions do not generate labels, but use them if they are available. Among -others, the branch and jump instructions will generate labels for the target -of the branch in the first pass. External labels (taken from the info file) -have precedence over internally generated ones, They must be valid identifiers -as specified for the ca65 assembler. Internal labels (generated by the -disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal -address of the label in upper case letters. You should probably avoid using -such label names for external labels. - - -<sect1>Info File<p> - -The info file is used to pass additional information about the input code to -the disassembler. This includes label names, data areas or tables, and global -options like input and output file names. See the <ref id="infofile" -name="next section"> for more information. - - - -<sect>Info File Format<label id="infofile"><p> - -The info file contains lists of specifications grouped together. Each group -directive has an identifying token and an attribute list enclosed in curly -braces. Attributes have a name followed by a value. The syntax of the value -depends on the type of the attribute. String attributes are places in double -quotes, numeric attributes may be specified as decimal numbers or hexadecimal -with a leading dollar sign. There are also attributes where the attribute -value is a keyword, in this case the keyword is given as is (without quotes or -anything). Each attribute is terminated by a semicolon. - -<tscreen><verb> - group-name { attribute1 attribute-value; attribute2 attribute-value; } -</verb></tscreen> - - -<sect1>Comments<p> - -Comments start with a hash mark (<tt/#/) and extend from the position of -the mark to the end of the current line. Hash marks inside of strings will -of course <em/not/ start a comment. - - -<sect1>Specifying global options<label id="global-options"><p> - -Global options may be specified in a group with the name <tt/GLOBAL/. The -following attributes are recognized: - -<descrip> - - <tag><tt/ARGUMENTCOLUMN/</tag> - This attribute specifies the column in the output, where the argument for - an opcode or pseudo instruction starts. The corresponding command line - option is - <tt><ref id="option--argument-column" name="--argument-column"></tt>. - - - <tag><tt/COMMENTCOLUMN/</tag> - This attribute specifies the column in the output, where the comment starts - in a line. It is only used for in-line comments. The corresponding command - line option is - <tt><ref id="option--comment-column" name="--comment-column"></tt>. - - - <label id="COMMENTS"> - <tag><tt/COMMENTS/</tag> - This attribute may be used instead of the <tt><ref id="option--comments" - name="--comments"></tt> option on the command line. It takes a numerical - parameter between 0 and 4. Higher values increase the amount of information - written to the output file in form of comments. - - - <tag><tt/CPU/</tag> - This attribute may be used instead of the <tt><ref id="option--cpu" - name="--cpu"></tt> option on the command line. For possible values see - there. The value is a string and must be enclosed in quotes. - - - <tag><tt/HEXOFFS/</tag> - The attribute is followed by a boolean value. If true, offsets to labels are - output in hex, otherwise they're output in decimal notation. The default is - false. The attribute may be changed on the command line using the <tt><ref - id="option--hexoffs" name="--hexoffs"></tt> option. - - - <tag><tt/INPUTNAME/</tag> - The attribute is followed by a string value, which gives the name of the - input file to read. If it is present, the disassembler does not accept an - input file name on the command line. - - - <tag><tt/INPUTOFFS/</tag> - The attribute is followed by a numerical value that gives an offset into - the input file which is skipped before reading data. The attribute may be - used to skip headers or unwanted code sections in the input file. - - - <tag><tt/INPUTSIZE/</tag> - <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of - data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/ - is ignored. - - - <label id="LABELBREAK"> - <tag><tt/LABELBREAK/</tag> - <tt/LABELBREAK/ is followed by a numerical value that specifies the label - length that will force a newline. To have all labels on their own lines, - you may set this value to zero. - - See also the <tt><ref id="option--label-break" name="--label-break"></tt> - command line option. A <tt/LABELBREAK/ statement in the info file will - override any value given on the command line. - - - <tag><tt/MNEMONICCOLUMN/</tag> - This attribute specifies the column in the output, where the mnemonic or - pseudo instruction is placed. The corresponding command line option is - <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>. - - - <tag><tt/NEWLINEAFTERJMP/</tag> - This attribute is followed by a boolean value. When true, a newline is - inserted after each <tt/JMP/ instruction. The default is false. - - - <tag><tt/NEWLINEAFTERRTS/</tag> - This attribute is followed by a boolean value. When true, a newline is - inserted after each <tt/RTS/ instruction. The default is false. - - - <label id="OUTPUTNAME"> - <tag><tt/OUTPUTNAME/</tag> - The attribute is followed by string value, which gives the name of the - output file to write. If it is present, specification of an output file on - the command line using the <tt><ref id="option-o" name="-o"></tt> option is - not allowed. - - The default is to use <tt/stdout/ for output, so without this attribute or - the corresponding command line option <tt/<ref id="option-o" name="-o">/ - the output will go to the terminal. - - - <tag><tt/PAGELENGTH/</tag> - This attribute may be used instead of the <tt><ref id="option--pagelength" - name="--pagelength"></tt> option on the command line. It takes a numerical - parameter. Using zero as page length (which is the default) means that no - pages are generated. - - - <tag><tt/STARTADDR/</tag> - This attribute may be used instead of the <tt><ref id="option--start-addr" - name="--start-addr"></tt> option on the command line. It takes a numerical - parameter. The default for the start address is $10000 minus the size of - the input file (this assumes that the input file is a ROM that contains the - reset and irq vectors). - - - <tag><tt/TEXTCOLUMN/</tag> - This attribute specifies the column, where the data bytes are output - translated into ASCII text. It is only used if - <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The - corresponding command line option is - <tt><ref id="option--text-column" name="--text-column"></tt>. - -</descrip> - - -<sect1>Specifying Ranges<p> - -The <tt/RANGE/ directive is used to give information about address ranges. The -following attributes are recognized: - -<descrip> - - <tag><tt>COMMENT</tt></tag> - This attribute is only allowed if a label is also given. It takes a string - as argument. See the description of the <tt><ref id="infofile-label" - name="LABEL"></tt> directive for an explanation. - - <tag><tt>END</tt></tag> - This gives the end address of the range. The end address is inclusive, that - means, it is part of the range. Of course, it may not be smaller than the - start address. - - <tag><tt>NAME</tt></tag> - This is a convenience attribute. It takes a string argument and will cause - the disassembler to define a label for the start of the range with the - given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt> - directive is not needed. - - <tag><tt>START</tt></tag> - This gives the start address of the range. - - <tag><tt>TYPE</tt></tag> - This attribute specifies the type of data within the range. The attribute - value is one of the following keywords: - - <descrip> - <tag><tt>ADDRTABLE</tt></tag> - The range consists of data and is disassembled as a table of words - (16 bit values). The difference to the <tt/WORDTABLE/ type is that - a label is defined for each entry in the table. - - <tag><tt>BYTETABLE</tt></tag> - The range consists of data and is disassembled as a byte table. - - <tag><tt>CODE</tt></tag> - The range consists of code. - - <tag><tt>DBYTETABLE</tt></tag> - The range consists of data and is disassembled as a table of dbytes - (double byte values, 16 bit values with the low byte containing the - most significant byte of the 16 bit value). - - <tag><tt>DWORDTABLE</tt></tag> - The range consists of data and is disassembled as a table of double - words (32 bit values). - - <tag><tt>RTSTABLE</tt></tag> - The range consists of data and is disassembled as a table of words (16 bit - values). The values are interpreted as words that are pushed onto the - stack and jump to it via <tt/RTS/. This means that they contain - <tt/address-1/ of a function, for which a label will get defined by the - disassembler. - - <tag><tt>SKIP</tt></tag> - The range is simply ignored when generating the output file. Please note - that this means that reassembling the output file will <em/not/ generate - the original file, not only because the missing piece in between, but also - because the following code will be located on wrong addresses. Output - generated with <tt/SKIP/ ranges will need manual rework. - - <tag><tt>TEXTTABLE</tt></tag> - The range consists of readable text. - - <tag><tt>WORDTABLE</tt></tag> - The range consists of data and is disassembled as a table of words - (16 bit values). - - </descrip> - -</descrip> - - -<sect1>Specifying Labels<label id="infofile-label"><p> - -The <tt/LABEL/ directive is used to give names for labels in the disassembled -code. The following attributes are recognized: - -<descrip> - - <tag><tt>ADDR</tt></tag> - Followed by a numerical value. Specifies the value of the label. - - <tag><tt>COMMENT</tt></tag> - Attribute argument is a string. The comment will show up in a separate line - before the label, if the label is within code or data range, or after the - label if it is outside. - - Example output: - -<tscreen><verb> - foo := $0001 ; Comment for label named "foo" - - ; Comment for label named "bar" - bar: -</verb></tscreen> - - <tag><tt>NAME</tt></tag> - The attribute is followed by a string value which gives the name of the - label. Empty names are allowed, in this case the disassembler will create - an unnamed label (see the assembler docs for more information about unnamed - labels). - - <tag><tt>SIZE</tt></tag> - This attribute is optional and may be used to specify the size of the data - that follows. If a size greater than 1 is specified, the disassembler will - create labels in the form <tt/label+offs/ for all bytes within the given - range, where <tt/label/ is the label name given with the <tt/NAME/ - attribute, and <tt/offs/ is the offset within the data. - -</descrip> - - -<sect1>Specifying Segments<label id="infofile-segment"><p> - -The <tt/SEGMENT/ directive is used to specify a segment within the -disassembled code. The following attributes are recognized: - -<descrip> - - <tag><tt>START</tt></tag> - Followed by a numerical value. Specifies the start address of the segment. - - <tag><tt>END</tt></tag> - Followed by a numerical value. Specifies the end address of the segment. The - end address is last the address that is part of the segment. - - <tag><tt>NAME</tt></tag> - The attribute is followed by a string value which gives the name of the - segment. -</descrip> - -All attributes are mandatory. Segments may not overlap. Since there is no -explicit "end this segment" pseudo op, the disassembler cannot notify the -assembler that one segment has ended. This may lead to errors if you don't -define your segments carefully. As a rule of thumb, if you're using segments, -your should define segments for all disassembled code. - - -<sect1>Specifying Assembler Includes<label id="infofile-asminc"><p> - -The <tt/ASMINC/ directive is used to give the names of input files containing -symbol assignments in assembler syntax: - -<tscreen><verb> - Name = value - Name := value -</verb></tscreen> - -The usual conventions apply for symbol names. Values may be specified as hex -(leading $), binary (leading %) or decimal. The values may optionally -be signed. - -NOTE: The include file parser is very simple. Expressions are not allowed, and -anything but symbol assignments is flagged as an error (but see the -<tt/IGNOREUNKNOWN/ directive below). - -The following attributes are recognized: - -<descrip> - - <tag><tt>FILE</tt></tag> - Followed by a string value. Specifies the name of the file to read. - - <tag><tt>COMMENTSTART</tt></tag> - The optional attribute is followed by a character constant. It specifies the - character that starts a comment. The default value is a semicolon. This - value is ignored if <tt/IGNOREUNKNOWN/ is true. - - <tag><tt>IGNOREUNKNOWN</tt></tag> - This attribute is optional and is followed by a boolean value. It allows to - ignore input lines that don't have a valid syntax. This allows to read in - assembler include files that contain more than just symbol assignments. - Note: When this attribute is used, the disassembler will ignore any errors - in the given include file. This may have undesired side effects. - -</descrip> - - -<sect1>An Info File Example<p> - -The following is a short example for an info file that contains most of the -directives explained above: - -<tscreen><verb> - # This is a comment. It extends to the end of the line - GLOBAL { - OUTPUTNAME "kernal.s"; - INPUTNAME "kernal.bin"; - STARTADDR $E000; - PAGELENGTH 0; # No paging - CPU "6502"; - }; - - # One segment for the whole stuff - SEGMENT { START $E000; END $FFFF; NAME kernal; }; - - RANGE { START $E612; END $E631; TYPE Code; }; - RANGE { START $E632; END $E640; TYPE ByteTable; }; - RANGE { START $EA51; END $EA84; TYPE RtsTable; }; - RANGE { START $EC6C; END $ECAB; TYPE RtsTable; }; - RANGE { START $ED08; END $ED11; TYPE AddrTable; }; - - # Zero page variables - LABEL { NAME "fnadr"; ADDR $90; SIZE 3; }; - LABEL { NAME "sal"; ADDR $93; }; - LABEL { NAME "sah"; ADDR $94; }; - LABEL { NAME "sas"; ADDR $95; }; - - # Stack - LABEL { NAME "stack"; ADDR $100; SIZE 255; }; - - # Indirect vectors - LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ - LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK - LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI - - # Jump table at end of kernal ROM - LABEL { NAME "kscrorg"; ADDR $FFED; }; - LABEL { NAME "kplot"; ADDR $FFF0; }; - LABEL { NAME "kiobase"; ADDR $FFF3; }; - LABEL { NAME "kgbye"; ADDR $FFF6; }; - - # Hardware vectors - LABEL { NAME "hanmi"; ADDR $FFFA; }; - LABEL { NAME "hares"; ADDR $FFFC; }; - LABEL { NAME "hairq"; ADDR $FFFE; }; -</verb></tscreen> - - - - - -<sect>Bugs/Feedback<p> - -If you have problems using the disassembler, if you find any bugs, or if -you're doing something interesting with the assembler, I would be glad to hear -from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>Copyright<p> - -da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von -Bassewitz. For usage of the binaries and/or sources the following -conditions do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - - - -</article> - - - - diff --git a/doc/debugging.sgml b/doc/debugging.sgml deleted file mode 100644 index 7566370b9..000000000 --- a/doc/debugging.sgml +++ /dev/null @@ -1,154 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Using emulators with cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>03.12.2000 - -<abstract> -How to debug your code using the VICE and Oricutron emulators. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This document describes how to debug your programs using the cc65 development -tools and the VICE CBM emulator. - - - -<sect>What is VICE?<p> - -VICE is an emulator for many of the CBM machines. It runs on Unix, MS-DOS, -Win32, OS/2, Acorn RISC OS, BeOS, QNX 6.x, Amiga, GP2X and Mac OS X. It emulates -the Commodore 64, 128, VIC20, PET and the 600/700 machines. For more information -see the VICE home page: - -<htmlurl url="http://www.viceteam.org/"> - -VICE has a builtin machine language monitor that may be used for debugging -your programs. Using an emulator for debugging has some advantages: - -<itemize> - -<item>Since you're using a crossassembler/-compiler anyway, you don't need to -transfer the program to the real machine until it is done. - -<item>An emulator allows many things that are almost impossible one of the -original machines. You may set watchpoints (detect read or write access to -arbitary addresses), debug interrupt handlers and even debug routines that run -inside the 1541 floppy. - -<item>You may use the label file generated by the linker to make much more use -from the monitor. - -</itemize> - - - -<sect>How to prepare your programs<p> - -VICE support is mostly done via a label file that is generated by the linker -and that may be read by the VICE monitor, so it knows about your program. -Source level debugging is <tt/not/ available, you have to debug your programs -in the assembler view. - -The first step is to generate object files that contain information about -<em/all/ labels in your sources, not just the exported ones. This can be done -by several means: - -<itemize> - -<item>Use the -g switch on the assembler command line. - -<item>Use the -<tscreen><verb> - .debuginfo + -</verb></tscreen> - command in your source. - -<item>Use the <tt/-g/ switch when invoking the compiler. The compiler will -then place a <tt/.debuginfo/ command into the generated assembler source. - -</itemize> - -So, if you have just C code, all you need is to invoke the compiler with -<tt/-g/. If you're using assembler code, you have to use <tt/-g/ for the -assembler, or add "<tt/.debuginfo on/" to your source files. Since the -generated debug info is not appended to the generated executables, it is a -good idea to always use <tt/-g/. It makes the object files and libraries -slightly larger (˜30%), but this is usually not a problem. - -The second step is to tell the linker that it should generate a VICE label -file. This is done by the <tt/-Ln/ switch followed by the name of the label -file (I'm usually using a <tt/.lbl/ extension for these files). An example for -a linker command line would be: - -<tscreen><verb> - ld65 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib -</verb></tscreen> -or -<tscreen><verb> - ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.lib -</verb></tscreen> - -This will generate a file named hello.lbl that contains all symbols used in -your program. - -<bf>Note</bf>: The runtime libraries and startup files were generated with -debug info, so you don't have to care about this. - - - -<sect>How to use the label file with VICE<p> - -Load your program, then enter the monitor and use the "<tt/ll/" command to -load your label file like this: - -<tscreen><verb> - ll "hello.lbl" -</verb></tscreen> - -You will get lots of warnings and even a few errors. You may ignore safely all -these warnings and errors as long as they reference any problems VICE thinks -it has with the labels. - -After loading the labels, they are used by VICE in the disassembler listing, -and you may use them whereever you need to specify an address. Try - -<tscreen><verb> - d ._main -</verb></tscreen> - -as an example (note that VICE needs a leading dot before all labels, and that -the compiler prepends an underline under most named labels). - - - -<sect>How to use the label file with Oricutron<p> - -Load your program, then enter the monitor and use the "<tt/sl/" command to -load your label file like this: - -<tscreen><verb> - sl hello.sym -</verb></tscreen> - -After loading the labels, they are used by Oricutron in the disassembler listing, -and you may use them whereever you need to specify an address. Try - -<tscreen><verb> - d ._main -</verb></tscreen> - -as an example (note that VICE needs a leading dot before all labels, and that -the compiler prepends an underline under most named labels). - - - -</article> diff --git a/doc/dio.sgml b/doc/dio.sgml deleted file mode 100644 index f340fa254..000000000 --- a/doc/dio.sgml +++ /dev/null @@ -1,134 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>Diskette Sector I/O Routines -<author>Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org"> -<date>20-Feb-2005 - -<abstract> -The cc65 library provides functions to read and write raw disk sectors. -Include the dio.h header file to get the necessary definitions. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Opening the disk for low level I/O<p> - -Prior to using these functions a handle to the device has to be obtained. This -is done with the <tt>dio_open</tt> function. After use, the handle should be -released with the <tt>dio_close</tt> function. - -<tscreen><verb> - dhandle_t __fastcall__ dio_open (unsigned char device); -</verb></tscreen> - -The <tt>device</tt> specifies the device to access, with 0 being the first -device, 1 the second, and so on. - -<tscreen><verb> - unsigned char __fastcall__ dio_close (dhandle_t handle); -</verb></tscreen> - -Closes a handle obtained by <tt>dio_open</tt>. Returns status code. -<p> - -<sect>Reading and writing sectors<p> - -The read and write functions are: - -<tscreen><verb> - unsigned char __fastcall__ dio_read (dhandle_t handle, - unsigned sect_num, - void *buffer); -</verb></tscreen> - -This function will read the sector specified by <tt>sect_num</tt> into the memory -location at buffer. - -<tscreen><verb> - unsigned char __fastcall__ dio_write (dhandle_t handle, - unsigned sect_num, - const void *buffer); -</verb></tscreen> - -This function will write the memory contents at buffer to the sector specified -by <tt>sect_num</tt>. No verify is performed. - -<tscreen><verb> - unsigned char __fastcall__ dio_write_verify (dhandle_t handle, - unsigned sect_num, - const void *buffer); -</verb></tscreen> - -This function will write the memory contents at buffer to the sector specified -by <tt>sect_num</tt>. A verification is performed. -<p> - -Use the <tt><ref name="dio_query_sectsize" id="sectsizecount"></tt> function to query -the size of a sector and the <tt><ref name="dio_query_sectcount" id="sectsizecount"></tt> -function to query the number of available sectors. -<p> - -All these functions will return 0 for success and an OS specific error code in -case of failure. -<p> - -<sect>Querying sector size and count<label id="sectsizecount"><p> - -Some systems support multiple diskette formats which have different sector sizes -and/or different sector counts. -<p> - -The following function returns the sector size of the currently inserted disk: - -<tscreen><verb> - unsigned __fastcall__ dio_query_sectsize (dhandle_t handle); -</verb></tscreen> - -On the Atari platform, the sector size is handled specially. Please refer -to the DIO section in the <htmlurl url="atari.html" name="Atari"> -specific platform documentation. -<p> - -The following function returns the sector count of the currently inserted disk: - -<tscreen><verb> - unsigned __fastcall__ dio_query_sectcount (dhandle_t handle); -</verb></tscreen> - -<sect>Converting sector numbers<p> - -Since the read and write functions expect a sector number, for systems where -the sectors aren't addressed by a logical sector number (e.g. CBM devices), -there are 2 conversion functions. One of them converts a logical sector number -to a head/track/sector triple. The other conversion function works the other -way round. - -<tscreen><verb> - unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle, - const dio_phys_pos *physpos, - unsigned *sectnum); -</verb></tscreen> - -This function converts track/head/sector to logical sector number. - -<tscreen><verb> - unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle, - const unsigned *sectnum, - dio_phys_pos *physpos); -</verb></tscreen> - -This function converts a logical sector number to track/head/sector notation. -<p> - -Note, that on systems which natively use logical sector numbers (e.g. Atari), -the conversion functions are dummies. They ignore head/track -(<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>). -The logical sector number is returned as physical sector and vice versa. -<p> - - -</article> diff --git a/doc/funcref.sgml b/doc/funcref.sgml deleted file mode 100644 index ba8fb8abc..000000000 --- a/doc/funcref.sgml +++ /dev/null @@ -1,7439 +0,0 @@ -<!doctype linuxdoc system> <!-- -*- text-mode -*- --> - -<article> -<title>cc65 function reference -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>07.11.2002 - -<abstract> -cc65 is a C compiler for 6502 based systems. This function reference describes -the C functions available in the standard library. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Introduction<p> - -cc65 is a C compiler for 6502 based systems. It implements a subset of the ISO -C standard plus additional functions specially crafted for 6502 systems or -just some of the supported machines. This function refrence describes the -available functions together with any limitations. - -For an overview about the available libraries, their purpose, and any -differences to the ISO standard, please have a look at the <htmlurl -url="library.html" name="cc65 Library Overview">. - -<bf/Note:/ Standard C functions are listed here, but not described in detail. -Since these functions behave identical on all standard compliant systems, they -are described in any book covering standard C. - -Each entry for a function contains a detailed description - -<quote> -<descrip> -<tag/Function/Summary of what <bf/function/ does. -<tag/Header/The header file that contains the declaration. -<tag/Declaration/Describes the needed header files and declaration of the -function. -<tag/Description/Description of the function. -<tag/Limits/Limits. -<tag/Availability/The availability of the function. -<tag/See also/Other related functions. -<tag/Example/A piece of actual code using the function. -</descrip> -</quote> - - -<sect>Functions by header file<p> - -<sect1><tt/6502.h/<label id="6502.h"><p> - -<itemize> -<item><ref id="BRK" name="BRK"> -<item><ref id="CLI" name="CLI"> -<item><ref id="SEI" name="SEI"> -<item><ref id="_sys" name="_sys"> -<item><ref id="getcpu" name="getcpu"> -<item><ref id="reset_brk" name="reset_brk"> -<item><ref id="reset_irq" name="reset_irq"> -<item><ref id="set_brk" name="set_brk"> -<item><ref id="set_irq" name="set_irq"> -</itemize> - - -<sect1><tt/apple2.h/<label id="apple2.h"><p> - -<itemize> -<item>_dos_type -<item><ref id="get_ostype" name="get_ostype"> -<item>rebootafterexit -</itemize> - - -<sect1><tt/apple2enh.h/<label id="apple2enh.h"><p> - -<itemize> -<item>_dos_type -<item><ref id="get_ostype" name="get_ostype"> -<item>rebootafterexit -<item>textframe -<item>textframexy -<item><ref id="videomode" name="videomode"> -</itemize> - - -<sect1><tt/assert.h/<label id="assert.h"><p> - -<itemize> -<item><ref id="assert" name="assert"> -</itemize> - - -<sect1><tt/atari.h/<label id="atari.h"><p> - -<itemize> -<!-- <item><ref id="_getcolor" name="_getcolor"> --> -<!-- <item><ref id="_getdefdev" name="_getdefdev"> --> -<!-- <item><ref id="_graphics" name="_graphics"> --> -<!-- <item><ref id="_rest_vecs" name="_rest_vecs"> --> -<!-- <item><ref id="_save_vecs" name="_save_vecs"> --> -<!-- <item><ref id="_scroll" name="_scroll"> --> -<!-- <item><ref id="_setcolor" name="_setcolor"> --> -<!-- <item><ref id="_setcolor_low" name="_setcolor_low"> --> -<item><ref id="get_ostype" name="get_ostype"> -<!-- <item><ref id="get_tv" name="get_tv"> --> -</itemize> - -(incomplete) - - -<sect1><tt/atmos.h/<label id="atmos.h"><p> - -<itemize> -<item><ref id="atmos_load" name="atmos_load"> -<item><ref id="atmos_save" name="atmos_save"> -</itemize> - - -<sect1><tt/c128.h/<label id="c128.h"><p> - -<itemize> -<item><ref id="c64mode" name="c64mode"> -<item><ref id="fast" name="fast"> -<item><ref id="slow" name="slow"> -<item><ref id="toggle_videomode" name="toggle_videomode"> -<item><ref id="videomode" name="videomode"> -</itemize> - - -<sect1><tt/c16.h/<label id="c16.h"><p> - -(incomplete) - - -<sect1><tt/c64.h/<label id="c64.h"><p> - -<itemize> -<item><ref id="get_ostype" name="get_ostype"> -</itemize> - - -<sect1><tt/cbm.h/<label id="cbm.h"><p> - -<itemize> -<item><ref id="cbm_k_acptr" name="cbm_k_acptr"> -<item><ref id="cbm_k_basin" name="cbm_k_basin"> -<item><ref id="cbm_k_bsout" name="cbm_k_bsout"> -<item><ref id="cbm_k_chkin" name="cbm_k_chkin"> -<item><ref id="cbm_k_ciout" name="cbm_k_ciout"> -<item><ref id="cbm_k_ckout" name="cbm_k_ckout"> -<item><ref id="cbm_k_clall" name="cbm_k_clall"> -<item><ref id="cbm_k_close" name="cbm_k_close"> -<item><ref id="cbm_k_clrch" name="cbm_k_clrch"> -<item><ref id="cbm_k_getin" name="cbm_k_getin"> -<item><ref id="cbm_k_iobase" name="cbm_k_iobase"> -<item><ref id="cbm_k_listen" name="cbm_k_listen"> -<item><ref id="cbm_k_load" name="cbm_k_load"> -<item><ref id="cbm_k_open" name="cbm_k_open"> -<item><ref id="cbm_k_readst" name="cbm_k_readst"> -<item><ref id="cbm_k_save" name="cbm_k_save"> -<item><ref id="cbm_k_setlfs" name="cbm_k_setlfs"> -<item><ref id="cbm_k_setnam" name="cbm_k_setnam"> -<item><ref id="cbm_k_unlsn" name="cbm_k_unlsn"> -<!-- <item><ref id="cbm_load" name="cbm_load"> --> -<!-- <item><ref id="cbm_open" name="cbm_open"> --> -<!-- <item><ref id="cbm_opendir" name="cbm_opendir"> --> -<!-- <item><ref id="cbm_read" name="cbm_read"> --> -<!-- <item><ref id="cbm_readdir" name="cbm_readdir"> --> -<!-- <item><ref id="cbm_save" name="cbm_save"> --> -<!-- <item><ref id="cbm_write" name="cbm_write"> --> -</itemize> - -(incomplete) - - -<sect1><tt/cbm510.h/<label id="cbm510.h"><p> - -<itemize> -<item><ref id="peekbsys" name="peekbsys"> -<item><ref id="peekwsys" name="peekwsys"> -<item><ref id="pokebsys" name="pokebsys"> -<item><ref id="pokewsys" name="pokewsys"> -</itemize> - - -<sect1><tt/cbm610.h/<label id="cbm610.h"><p> - -<itemize> -<item><ref id="peekbsys" name="peekbsys"> -<item><ref id="peekwsys" name="peekwsys"> -<item><ref id="pokebsys" name="pokebsys"> -<item><ref id="pokewsys" name="pokewsys"> -</itemize> - - -<sect1><tt/cc65.h/<label id="cc65.h"><p> - -<!-- <itemize> --> -<!-- <item><ref id="cc65_cos" name="cc65_cos"> --> -<!-- <item><ref id="cc65_idiv32by16r16" name="cc65_idiv32by16r16"> --> -<!-- <item><ref id="cc65_imul16x16r32" name="cc65_imul16x16r32"> --> -<!-- <item><ref id="cc65_imul8x8r16" name="cc65_imul8x8r16"> --> -<!-- <item><ref id="cc65_sin" name="cc65_sin"> --> -<!-- <item><ref id="cc65_udiv32by16r16" name="cc65_udiv32by16r16"> --> -<!-- <item><ref id="cc65_umul16x16r32" name="cc65_umul16x16r32"> --> -<!-- <item><ref id="cc65_umul16x8r32" name="cc65_umul16x8r32"> --> -<!-- <item><ref id="cc65_umul8x8r16" name="cc65_umul8x8r16"> --> -<!-- </itemize> --> - -(incomplete) - - -<sect1><tt/conio.h/<label id="conio.h"><p> - -<itemize> -<item><ref id="bgcolor" name="bgcolor"> -<item><ref id="bordercolor" name="bordercolor"> -<item><ref id="cclear" name="cclear"> -<item><ref id="cclearxy" name="cclearxy"> -<item><ref id="cgetc" name="cgetc"> -<item><ref id="chline" name="chline"> -<item><ref id="chlinexy" name="chlinexy"> -<item><ref id="clrscr" name="clrscr"> -<item><ref id="cprintf" name="cprintf"> -<item><ref id="cputc" name="cputc"> -<item><ref id="cputcxy" name="cputcxy"> -<item><ref id="cputs" name="cputs"> -<item><ref id="cputsxy" name="cputsxy"> -<item><ref id="cursor" name="cursor"> -<item><ref id="cvline" name="cvline"> -<item><ref id="cvlinexy" name="cvlinexy"> -<item><ref id="gotox" name="gotox"> -<item><ref id="gotoxy" name="gotoxy"> -<item><ref id="gotoy" name="gotoy"> -<item><ref id="kbhit" name="kbhit"> -<item><ref id="revers" name="revers"> -<item><ref id="screensize" name="screensize"> -<item><ref id="textcolor" name="textcolor"> -<item><ref id="vcprintf" name="vcprintf"> -<item><ref id="wherex" name="wherex"> -<item><ref id="wherey" name="wherey"> -</itemize> - - -<sect1><tt/ctype.h/<label id="ctype.h"><p> - -<itemize> -<item><ref id="isalnum" name="isalnum"> -<item><ref id="isalpha" name="isalpha"> -<item><ref id="isascii" name="isascii"> -<item><ref id="isblank" name="isblank"> -<item><ref id="iscntrl" name="iscntrl"> -<item><ref id="isdigit" name="isdigit"> -<item><ref id="isgraph" name="isgraph"> -<item><ref id="islower" name="islower"> -<item><ref id="isprint" name="isprint"> -<item><ref id="ispunct" name="ispunct"> -<item><ref id="isspace" name="isspace"> -<item><ref id="isupper" name="isupper"> -<item><ref id="isxdigit" name="isxdigit"> -<item><ref id="tolower" name="tolower"> -<item><ref id="toupper" name="toupper"> -</itemize> - - -<sect1><tt/dbg.h/<label id="dbg.h"><p> - -<!-- <itemize> --> -<!-- <item><ref id="DbgInit" name="DbgInit"> --> -<!-- </itemize> --> - -(incomplete) - - -<sect1><tt/dio.h/<label id="dio.h"><p> - -<htmlurl url="dio.html" name="dio.html"> -Low-level disk I/O API. - - -<sect1><tt/dirent.h/<label id="dirent.h"><p> - -<itemize> -<item><ref id="_DE_ISDIR" name="_DE_ISDIR"> -<item><ref id="_DE_ISLBL" name="_DE_ISLBL"> -<item><ref id="_DE_ISLNK" name="_DE_ISLNK"> -<item><ref id="_DE_ISREG" name="_DE_ISREG"> -<item><ref id="closedir" name="closedir"> -<item><ref id="opendir" name="opendir"> -<item><ref id="readdir" name="readdir"> -<item><ref id="rewinddir" name="rewinddir"> -<item><ref id="seekdir" name="seekdir"> -<item><ref id="telldir" name="telldir"> -</itemize> - -(incomplete) - - -<sect1><tt/em.h/<label id="em.h"><p> - -<itemize> -<item><ref id="em_commit" name="em_commit"> -<item><ref id="em_copyfrom" name="em_copyfrom"> -<item><ref id="em_copyto" name="em_copyto"> -<item><ref id="em_install" name="em_install"> -<item><ref id="em_load_driver" name="em_load_driver"> -<item><ref id="em_map" name="em_map"> -<item><ref id="em_pagecount" name="em_pagecount"> -<item><ref id="em_uninstall" name="em_uninstall"> -<item><ref id="em_unload" name="em_unload"> -<item><ref id="em_use" name="em_use"> -</itemize> - - -<sect1><tt/errno.h/<label id="errno.h"><p> - -<!-- <itemize> --> -<!-- <item><ref id="_directerrno" name="_directerrno"> --> -<!-- <item><ref id="_mappederrno" name="_mappederrno"> --> -<!-- <item><ref id="_osmaperrno" name="_osmaperrno"> --> -<!-- <item><ref id="_seterrno" name="_seterrno"> --> -<!-- </itemize> --> - -(incomplete) - - -<sect1><tt/fcntl.h/<label id="fcntl.h"><p> - -<itemize> -<item><ref id="close" name="close"> -<item><ref id="creat" name="creat"> -<item><ref id="open" name="open"> -</itemize> - - -<sect1><tt/geos.h/<label id="geos.h"><p> - -(incomplete) - - -<sect1><tt/joystick.h/<label id="joystick.h"><p> - -<itemize> -<item><ref id="joy_count" name="joy_count"> -<item><ref id="joy_install" name="joy_install"> -<item><ref id="joy_load_driver" name="joy_load_driver"> -<item><ref id="joy_read" name="joy_read"> -<item><ref id="joy_uninstall" name="joy_uninstall"> -<item><ref id="joy_unload" name="joy_unload"> -</itemize> - - -<sect1><tt/locale.h/<label id="locale.h"><p> - -<itemize> -<item><ref id="localeconv" name="localeconv"> -<item><ref id="setlocale" name="setlocale"> -</itemize> - - -<sect1><tt/lynx.h/<label id="lynx.h"><p> - -<!-- <itemize> --> -<!-- <item><ref id="lynx_eeprom_erase" name="lynx_eeprom_erase"> --> -<!-- <item><ref id="lynx_eeprom_read" name="lynx_eeprom_read"> --> -<!-- <item><ref id="lynx_eeprom_write" name="lynx_eeprom_write"> --> -<!-- <item><ref id="lynx_eeread" name="lynx_eeread"> --> -<!-- <item><ref id="lynx_eewrite" name="lynx_eewrite"> --> -<!-- <item><ref id="lynx_exec" name="lynx_exec"> --> -<!-- <item><ref id="lynx_load" name="lynx_load"> --> -<!-- </itemize> --> - -(incomplete) - - -<sect1><tt/modload.h/<label id="modload.h"><p> - -<itemize> -<item><ref id="mod_load" name="mod_load"> -<item><ref id="mod_free" name="mod_free"> -</itemize> - - -<sect1><tt/mouse.h/<label id="mouse.h"><p> - -<itemize> -<item><ref id="mouse_buttons" name="mouse_buttons"> -<item><ref id="mouse_getbox" name="mouse_getbox"> -<item><ref id="mouse_geterrormsg" name="mouse_geterrormsg"> -<item><ref id="mouse_hide" name="mouse_hide"> -<item><ref id="mouse_info" name="mouse_info"> -<item><ref id="mouse_install" name="mouse_install"> -<item><ref id="mouse_ioctl" name="mouse_ioctl"> -<item><ref id="mouse_load_driver" name="mouse_load_driver"> -<item><ref id="mouse_move" name="mouse_move"> -<item><ref id="mouse_pos" name="mouse_pos"> -<item><ref id="mouse_setbox" name="mouse_setbox"> -<item><ref id="mouse_show" name="mouse_show"> -<item><ref id="mouse_uninstall" name="mouse_uninstall"> -<item><ref id="mouse_unload" name="mouse_unload"> -</itemize> - - -<sect1><tt/nes.h/<label id="nes.h"><p> - -<!-- <itemize> --> -<!-- <item><ref id="get_tv" name="get_tv"> --> -<!-- <item><ref id="waitvblank" name="waitvblank"> --> -<!-- </itemize> --> - -(incomplete) - - -<sect1><tt/o65.h/<label id="o65.h"><p> - -The <tt/o65.h/ header file contains structure and constant definitions that -may be used when dealing with files in <htmlurl -url="http://www.6502.org/users/andre/o65/fileformat.html" name="o65 format">. -It does not declare any functions. - - -<sect1><tt/peekpoke.h/<label id="peekpoke.h"><p> - -<itemize> -<item><ref id="PEEK" name="PEEK"> -<item><ref id="PEEKW" name="PEEKW"> -<item><ref id="POKE" name="POKE"> -<item><ref id="POKEW" name="POKEW"> -</itemize> - - -<sect1><tt/pet.h/<label id="pet.h"><p> - -(incomplete) - - -<sect1><tt/plus4.h/<label id="plus4.h"><p> - -(incomplete) - - -<sect1><tt/serial.h/<label id="serial.h"><p> - -The <tt/serial.h/ header file contains definitions for initializing serial -communication. - -<itemize> -<item><ref id="ser_close" name="ser_close"> -<item><ref id="ser_get" name="ser_get"> -<item><ref id="ser_install" name="ser_install"> -<item><ref id="ser_ioctl" name="ser_ioctl"> -<item><ref id="ser_load_driver" name="ser_load_driver"> -<item><ref id="ser_open" name="ser_open"> -<item><ref id="ser_put" name="ser_put"> -<item><ref id="ser_status" name="ser_status"> -<item><ref id="ser_uninstall" name="ser_uninstall"> -<item><ref id="ser_unload" name="ser_unload"> -</itemize> - - -<sect1><tt/setjmp.h/<label id="setjmp.h"><p> - -<itemize> -<item><ref id="setjmp" name="setjmp"> -<item><ref id="longjmp" name="longjmp"> -</itemize> - - -<sect1><tt/signal.h/<label id="signal.h"><p> - -<itemize> -<item><ref id="raise" name="raise"> -<item><ref id="signal" name="signal"> -</itemize> - - -<sect1><tt/stdarg.h/<label id="stdarg.h"><p> - -(incomplete) - - -<sect1><tt/stdbool.h/<label id="stdbool.h"><p> - -(incomplete) - - -<sect1><tt/stddef.h/<label id="stddef.h"><p> - -<itemize> -<item><ref id="offsetof" name="offsetof"> -</itemize> - - -<sect1><tt/stdio.h/<label id="stdio.h"><p> - -<itemize> -<item><ref id="_poserror" name="_poserror"> -<item><ref id="clearerr" name="clearerr"> -<!-- <item><ref id="fclose" name="fclose"> --> -<!-- <item><ref id="fdopen" name="fdopen"> --> -<item><ref id="feof" name="feof"> -<item><ref id="ferror" name="ferror"> -<!-- <item><ref id="fflush" name="fflush"> --> -<!-- <item><ref id="fgetc" name="fgetc"> --> -<!-- <item><ref id="fgetpos" name="fgetpos"> --> -<!-- <item><ref id="fgets" name="fgets"> --> -<item><ref id="fileno" name="fileno"> -<!-- <item><ref id="fopen" name="fopen"> --> -<!-- <item><ref id="fprintf" name="fprintf"> --> -<!-- <item><ref id="fputc" name="fputc"> --> -<!-- <item><ref id="fputs" name="fputs"> --> -<!-- <item><ref id="fread" name="fread"> --> -<!-- <item><ref id="freopen" name="freopen"> --> -<!-- <item><ref id="fscanf" name="fscanf"> --> -<!-- <item><ref id="fseek" name="fseek"> --> -<!-- <item><ref id="fsetpos" name="fsetpos"> --> -<!-- <item><ref id="ftell" name="ftell"> --> -<!-- <item><ref id="fwrite" name="fwrite"> --> -<!-- <item><ref id="getc" name="getc"> --> -<!-- <item><ref id="getchar" name="getchar"> --> -<!-- <item><ref id="gets" name="gets"> --> -<!-- <item><ref id="printf" name="printf"> --> -<!-- <item><ref id="putc" name="putc"> --> -<!-- <item><ref id="putchar" name="putchar"> --> -<!-- <item><ref id="puts" name="puts"> --> -<item><ref id="rename" name="rename"> -<item><ref id="remove" name="remove"> -<!-- <item><ref id="rewind" name="rewind"> --> -<!-- <item><ref id="scanf" name="scanf"> --> -<!-- <item><ref id="snprintf" name="snprintf"> --> -<!-- <item><ref id="sprintf" name="sprintf"> --> -<!-- <item><ref id="sscanf" name="sscanf"> --> -<!-- <item><ref id="vfprintf" name="vfprintf"> --> -<!-- <item><ref id="vfscanf" name="vfscanf"> --> -<!-- <item><ref id="vprintf" name="vprintf"> --> -<!-- <item><ref id="vscanf" name="vscanf"> --> -<!-- <item><ref id="vsnprintf" name="vsnprintf"> --> -<!-- <item><ref id="vsprintf" name="vsprintf"> --> -<!-- <item><ref id="vsscanf" name="vsscanf"> --> -</itemize> - -(incomplete) - - -<sect1><tt/stdlib.h/<label id="stdlib.h"><p> - -<itemize> -<item><ref id="_heapadd" name="_heapadd"> -<item><ref id="_heapblocksize" name="_heapblocksize"> -<item><ref id="_heapmaxavail" name="_heapmaxavail"> -<item><ref id="_heapmemavail" name="_heapmemavail"> -<item><ref id="_randomize" name="_randomize"> -<item><ref id="_swap" name="_swap"> -<item><ref id="abort" name="abort"> -<item><ref id="abs" name="abs"> -<item><ref id="atexit" name="atexit"> -<item><ref id="atoi" name="atoi"> -<item><ref id="atol" name="atol"> -<item><ref id="bsearch" name="bsearch"> -<item><ref id="calloc" name="calloc"> -<item><ref id="div" name="div"> -<item><ref id="exit" name="exit"> -<item><ref id="free" name="free"> -<item><ref id="getenv" name="getenv"> -<item><ref id="itoa" name="itoa"> -<item><ref id="labs" name="labs"> -<item><ref id="ltoa" name="ltoa"> -<item><ref id="malloc" name="malloc"> -<item><ref id="perror" name="perror"> -<!-- <item><ref id="posix_memalign" name="posix_memalign"> --> -<!-- <item><ref id="putenv" name="putenv"> --> -<item><ref id="qsort" name="qsort"> -<item><ref id="rand" name="rand"> -<item><ref id="realloc" name="realloc"> -<item><ref id="srand" name="srand"> -<!-- <item><ref id="system" name="system"> --> -<item><ref id="ultoa" name="ultoa"> -<item><ref id="utoa" name="utoa"> -</itemize> - -(incomplete) - - -<sect1><tt/string.h/<label id="string.h"><p> - -<itemize> -<item><ref id="_stroserror" name="_stroserror"> -<item><ref id="bzero" name="bzero"> -<item><ref id="memchr" name="memchr"> -<item><ref id="memcmp" name="memcmp"> -<item><ref id="memcpy" name="memcpy"> -<item><ref id="memmove" name="memmove"> -<item><ref id="memset" name="memset"> -<item><ref id="strcasecmp" name="strcasecmp"> -<item><ref id="strcat" name="strcat"> -<item><ref id="strchr" name="strchr"> -<item><ref id="strcmp" name="strcmp"> -<item><ref id="strcoll" name="strcoll"> -<item><ref id="strcpy" name="strcpy"> -<item><ref id="strcspn" name="strcspn"> -<item><ref id="strdup" name="strdup"> -<item><ref id="strerror" name="strerror"> -<item><ref id="stricmp" name="stricmp"> -<item><ref id="strlen" name="strlen"> -<item><ref id="strlower" name="strlower"> -<item><ref id="strlwr" name="strlwr"> -<item><ref id="strncat" name="strncat"> -<item><ref id="strncmp" name="strncmp"> -<item><ref id="strncpy" name="strncpy"> -<item><ref id="strrchr" name="strrchr"> -<item><ref id="strspn" name="strspn"> -<item><ref id="strstr" name="strstr"> -<item><ref id="strtok" name="strtok"> -<item><ref id="strxfrm" name="strxfrm"> -<item><ref id="strupper" name="strupper"> -<item><ref id="strupr" name="strupr"> -</itemize> - -(incomplete) - - -<sect1><tt/tgi.h/<label id="tgi.h"><p> - -<itemize> -<item><ref id="tgi_arc" name="tgi_arc"> -<item><ref id="tgi_bar" name="tgi_bar"> -<item><ref id="tgi_circle" name="tgi_circle"> -<item><ref id="tgi_clear" name="tgi_clear"> -<item><ref id="tgi_done" name="tgi_done"> -<item><ref id="tgi_ellipse" name="tgi_ellipse"> -<item><ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> -<item><ref id="tgi_getaspectratio" name="tgi_getaspectratio"> -<item><ref id="tgi_getcolor" name="tgi_getcolor"> -<item><ref id="tgi_getcolorcount" name="tgi_getcolorcount"> -<item><ref id="tgi_getdefpalette" name="tgi_getdefpalette"> -<item><ref id="tgi_geterror" name="tgi_geterror"> -<item><ref id="tgi_geterrormsg" name="tgi_geterrormsg"> -<item><ref id="tgi_getmaxcolor" name="tgi_getmaxcolor"> -<item><ref id="tgi_getmaxx" name="tgi_getmaxx"> -<item><ref id="tgi_getmaxy" name="tgi_getmaxy"> -<item><ref id="tgi_getpagecount" name="tgi_getpagecount"> -<item><ref id="tgi_getpalette" name="tgi_getpalette"> -<item><ref id="tgi_getpixel" name="tgi_getpixel"> -<item><ref id="tgi_gettextheight" name="tgi_gettextheight"> -<item><ref id="tgi_gettextwidth" name="tgi_gettextwidth"> -<item><ref id="tgi_getxres" name="tgi_getxres"> -<item><ref id="tgi_getyres" name="tgi_getyres"> -<item><ref id="tgi_gotoxy" name="tgi_gotoxy"> -<item><ref id="tgi_init" name="tgi_init"> -<item><ref id="tgi_install" name="tgi_install"> -<item><ref id="tgi_install_vectorfont" name="tgi_install_vectorfont"> -<item><ref id="tgi_ioctl" name="tgi_ioctl"> -<item><ref id="tgi_line" name="tgi_line"> -<item><ref id="tgi_lineto" name="tgi_lineto"> -<item><ref id="tgi_load_driver" name="tgi_load_driver"> -<item><ref id="tgi_load_vectorfont" name="tgi_load_vectorfont"> -<item><ref id="tgi_outtext" name="tgi_outtext"> -<item><ref id="tgi_outtextxy" name="tgi_outtextxy"> -<item><ref id="tgi_setaspectratio" name="tgi_setaspectratio"> -<item><ref id="tgi_setcolor" name="tgi_setcolor"> -<item><ref id="tgi_setdrawpage" name="tgi_setdrawpage"> -<item><ref id="tgi_setpalette" name="tgi_setpalette"> -<item><ref id="tgi_setpixel" name="tgi_setpixel"> -<item><ref id="tgi_setviewpage" name="tgi_setviewpage"> -<item><ref id="tgi_settextscale" name="tgi_settextscale"> -<item><ref id="tgi_settextstyle" name="tgi_settextstyle"> -<item><ref id="tgi_uninstall" name="tgi_uninstall"> -<item><ref id="tgi_unload" name="tgi_unload"> -</itemize> - -<sect1><tt/time.h/<label id="time.h"><p> - -<itemize> -<!-- <item><ref id="_systime" name="_systime"> --> -<!-- <item><ref id="asctime" name="asctime"> --> -<item><ref id="clock" name="clock"> -<!-- <item><ref id="ctime" name="ctime"> --> -<!-- <item><ref id="gmtime" name="gmtime"> --> -<!-- <item><ref id="localtime" name="localtime"> --> -<!-- <item><ref id="mktime" name="mktime"> --> -<!-- <item><ref id="strftime" name="strftime"> --> -<item><ref id="time" name="time"> -</itemize> - -(incomplete) - - -<sect1><tt/unistd.h/<label id="unistd.h"><p> - -<itemize> -<!-- <item><ref id="chdir" name="chdir"> --> -<item><ref id="exec" name="exec"> -<!-- <item><ref id="getcwd" name="getcwd"> --> -<item><ref id="getopt" name="getopt"> -<!-- <item><ref id="lseek" name="lseek"> --> -<!-- <item><ref id="mkdir" name="mkdir"> --> -<!-- <item><ref id="read" name="read"> --> -<!-- <item><ref id="rmdir" name="rmdir"> --> -<item><ref id="sleep" name="sleep"> -<item><ref id="unlink" name="unlink"> -<!-- <item><ref id="write" name="write"> --> -</itemize> - -(incomplete) - - -<sect1><tt/vic20.h/<label id="vic20.h"><p> - -(incomplete) - - -<sect1><tt/zlib.h/<label id="zlib.h"><p> - -<!-- <itemize> --> -<!-- <item><ref id="adler32" name="adler32"> --> -<!-- <item><ref id="crc32" name="crc32"> --> -<!-- <item><ref id="inflatemem" name="inflatemem"> --> -<!-- <item><ref id="uncompress" name="uncompress"> --> -<!-- </itemize> --> - -(incomplete) - - -<sect>Alphabetical function reference<p> - -<sect1>_DE_ISDIR<label id="_DE_ISDIR"><p> - -<quote> -<descrip> -<tag/Function/Determine if a directory entry specifies a directory. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/int _DE_ISDIR(unsigned char type);/ -<tag/Description/The function is called with the type of a directory entry -taken from a <tt/struct dirent/ and returns true if the entry designates -a directory. -<tag/Limits/ -<itemize> -<item>The function is actually a macro. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_DE_ISLBL" name="_DE_ISLBL">, -<ref id="_DE_ISLNK" name="_DE_ISLNK">, -<ref id="_DE_ISREG" name="_DE_ISREG"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_DE_ISLBL<label id="_DE_ISLBL"><p> - -<quote> -<descrip> -<tag/Function/Determine if a directory entry specifies a disk label. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/int _DE_ISLBL(unsigned char type);/ -<tag/Description/The function is called with the type of a directory entry -taken from a <tt/struct dirent/ and returns true if the entry designates -a disk label. -<tag/Limits/ -<itemize> -<item>The function is actually a macro. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_DE_ISDIR" name="_DE_ISDIR">, -<ref id="_DE_ISLNK" name="_DE_ISLNK">, -<ref id="_DE_ISREG" name="_DE_ISREG"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_DE_ISLNK<label id="_DE_ISLNK"><p> - -<quote> -<descrip> -<tag/Function/Determine if a directory entry specifies a link. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/int _DE_ISLNK(unsigned char type);/ -<tag/Description/The function is called with the type of a directory entry -taken from a <tt/struct dirent/ and returns true if the entry designates -a link. -<tag/Limits/ -<itemize> -<item>The function is actually a macro. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_DE_ISDIR" name="_DE_ISDIR">, -<ref id="_DE_ISLBL" name="_DE_ISLBL">, -<ref id="_DE_ISREG" name="_DE_ISREG"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_DE_ISREG<label id="_DE_ISREG"><p> - -<quote> -<descrip> -<tag/Function/Determine if a directory entry specifies a regular file. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/int _DE_ISREG(unsigned char type);/ -<tag/Description/The function is called with the type of a directory entry -taken from a <tt/struct dirent/ and returns true if the entry designates -a regular file. -<tag/Limits/ -<itemize> -<item>The function is actually a macro. -<item>A "regular file" means anything with data in it. This might still mean -that special processing is needed, when accessing the file. Relative files of -the CBM systems are classified as being "regular" files, for example. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_DE_ISDIR" name="_DE_ISDIR">, -<ref id="_DE_ISLBL" name="_DE_ISLBL">, -<ref id="_DE_ISLNK" name="_DE_ISLNK"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_heapadd<label id="_heapadd"><p> - -<quote> -<descrip> -<tag/Function/Add a block to the heap. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void __fastcall__ _heapadd (void* mem, size_t size);/ -<tag/Description/The function adds a block of raw memory to the heap. -<tag/Limits/ -<itemize> -<item>The minimum blocksize that can be added is 6 bytes; the function will -ignore smaller blocks. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_heapblocksize" name="_heapblocksize">, -<ref id="_heapmaxavail" name="_heapmaxavail">, -<ref id="_heapmemavail" name="_heapmemavail">, -<ref id="calloc" name="calloc">, -<ref id="free" name="free">, -<ref id="malloc" name="malloc">, -<ref id="realloc" name="realloc"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_heapblocksize<label id="_heapblocksize"><p> - -<quote> -<descrip> -<tag/Function/Return the size of an allocated block. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/size_t __fastcall__ _heapblocksize (const void* block);/ -<tag/Description/The function returns the size of a block that must have -previously been allocated by <tt/<ref id="malloc" name="malloc">/, <tt/<ref -id="calloc" name="calloc">/ or <tt/<ref id="realloc" name="realloc">/. -<tag/Limits/ -<itemize> -<item>Passing a pointer to a block that was is not the result of one of the -allocation functions, or that has been free'd will give unpredicable results. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_heapadd" name="_heapadd">, -<ref id="_heapmaxavail" name="_heapmaxavail">, -<ref id="_heapmemavail" name="_heapmemavail">, -<ref id="calloc" name="calloc">, -<ref id="free" name="free">, -<ref id="malloc" name="malloc">, -<ref id="realloc" name="realloc"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_heapmaxavail<label id="_heapmaxavail"><p> - -<quote> -<descrip> -<tag/Function/Return the largest block that is available on the heap. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/size_t _heapmaxavail (void);/ -<tag/Description/The function returns the size of the largest block that may -be allocated from the heap using <tt/<ref id="malloc" name="malloc">/. -<tag/Availability/cc65 -<tag/See also/ -<ref id="_heapadd" name="_heapadd">, -<ref id="_heapblocksize" name="_heapblocksize">, -<ref id="_heapmemavail" name="_heapmemavail">, -<ref id="calloc" name="calloc">, -<ref id="free" name="free">, -<ref id="malloc" name="malloc">, -<ref id="realloc" name="realloc"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_heapmemavail<label id="_heapmemavail"><p> - -<quote> -<descrip> -<tag/Function/Return the total available space on the heap. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/size_t __fastcall__ _heapmemavail (void);/ -<tag/Description/The function returns the total number of bytes available on -the heap. -<tag/Limits/ -<itemize> -<item>This function is of less use than usually assumed, since the returned -heap space may be available but not in one block. So even if this function -says that several times more heap space is available than needed, <ref -id="malloc" name="malloc"> may still return <tt/NULL/. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_heapadd" name="_heapadd">, -<ref id="_heapblocksize" name="_heapblocksize">, -<ref id="_heapmaxavail" name="_heapmaxavail">, -<ref id="calloc" name="calloc">, -<ref id="free" name="free">, -<ref id="malloc" name="malloc">, -<ref id="realloc" name="realloc"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_poserror<label id="_poserror"><p> - -<quote> -<descrip> -<tag/Function/Print an error message for the error in <tt/_oserror/. -<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ -<tag/Declaration/<tt/void __fastcall__ _poserror (const char* msg);/ -<tag/Description/<tt/_poserror/ prints an error message to <tt/stderr/. If -<tt/msg/ is not <tt/NULL/ and not an empty string, it is printed followed by -a colon and a blank. Then the error message for the current contents of -<tt/_oserror/ are printed followed by a newline. The message output is the -same as returned by <tt/<ref id="_stroserror" name="_stroserror">/ with an -argument of <tt/_oserror/. -<tag/Limits/ -<itemize> -<item>Since operating system specific error code are - you guessed it - -operating system specific, the value in <tt/_oserror/ and the message that is -printed depends on the cc65 target. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_stroserror" name="_stroserror">, -<ref id="perror" name="perror"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_randomize<label id="_randomize"><p> - -<quote> -<descrip> -<tag/Function/Initialize the pseudo random number generator. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void _randomize (void);/ -<tag/Description/The function initializes the random number generator with -a seed derived from fast changing hardware events, so the seed itself can be -considered random to a certain degree. -<tag/Limits/<itemize> -<item>The randomness of the seed depends on the machine hardware. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="rand" name="rand">, -<ref id="srand" name="srand"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_stroserror<label id="_stroserror"><p> - -<quote> -<descrip> -<tag/Function/Return a string describing an OS specific error code. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/const char* __fastcall__ _stroserror (unsigned char errcode);/ -<tag/Description/<tt/_stroserror/ will return a string describing the given -operating system specific error code. -<tag/Limits/<itemize> -<item>Since operating system specific error code are - you guessed it - -operating system specific, the parameter and the string returned depend on the -cc65 target. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="strerror" name="strerror"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_swap<label id="_swap"><p> - -<quote> -<descrip> -<tag/Function/Swap the contents of memory areas. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void __fastcall__ _swap (void* p, void* q, size_t size);/ -<tag/Description/<tt/_swap/ will swap (exchange) the contents of the two memory -areas pointed to by <tt/p/ and <tt/q/. Both memory areas are assumed to be -<tt/size/ bytes in size. -<tag/Limits/<itemize> -<item>The memory areas may not overlap, otherwise the results are undefined. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="memcpy" name="memcpy">, -<ref id="memmove" name="memmove"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>_sys<label id="_sys"><p> - -<quote> -<descrip> -<tag/Function/Call a subroutine passing register values. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/void __fastcall__ _sys (struct regs* r);/ -<tag/Description/The function will call the subroutine at the address -specified in the <tt/pc/ member of the passed <tt/regs/ structure. All -registers and the CPU flags are set to the values given in the <tt/regs/ -structure. On return from the subroutine, the new values of the registers and -flags are stored back overwriting the old values. -<tag/Limits/<itemize> -<item>Bits 4 and 5 of the flags value in the <tt/regs/ structure are ignored -when calling the subroutine (they are unchanged from their current values). -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/Example/None. -</descrip> -</quote> - - -<sect1>BRK<label id="BRK"><p> - -<quote> -<descrip> -<tag/Function/Insert a 6502 BRK instrunction into the code. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/void BRK (void);/ -<tag/Description/The function will insert a 6502 BRK instruction into the code -which may be used to trigger a debugger. -<tag/Limits/<itemize> -<item>The function is actually a macro. -<item>The inserted instruction may lead to unexpected results if no debugger -is present. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="CLI" name="CLI">, -<ref id="SEI" name="SEI"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>CLI<label id="CLI"><p> - -<quote> -<descrip> -<tag/Function/Insert a 6502 CLI instrunction into the code. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/void CLI (void);/ -<tag/Description/The function will insert a 6502 CLI instruction into the code, -so interrupts are enabled. Enabling interrupts has no effects if they are -already enabled (the default). -<tag/Limits/<itemize> -<item>The function is actually a macro. -<item>Disabling interrupts may lead to unexpected results. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="BRK" name="BRK">, -<ref id="SEI" name="SEI"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>PEEK<label id="PEEK"><p> - -<quote> -<descrip> -<tag/Function/Read a byte from memory. -<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ -<tag/Declaration/<tt/unsigned char PEEK (unsigned addr);/ -<tag/Description/The function will read the absolute memory given by <tt/addr/ -and return the value read. -<tag/Limits/<itemize> -<item>The function is actually a macro. -<item>This function depends highly on the platform and environment. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="PEEKW" name="PEEKW">, -<ref id="POKE" name="POKE"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>PEEKW<label id="PEEKW"><p> - -<quote> -<descrip> -<tag/Function/Read a word (two bytes) from memory. -<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ -<tag/Declaration/<tt/unsigned PEEKW (unsigned addr);/ -<tag/Description/The function will read the absolute memory given by <tt/addr/ -and return the value read. The byte read from the higher address is the high -byte of the return value. -<tag/Limits/<itemize> -<item>The function is actually a macro. -<item>This function depends highly on the platform and environment. -<item>The order in which the two bytes are read is unspecified and may -depend of the address expression used. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="PEEK" name="PEEK">, -<ref id="POKE" name="POKE"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>POKE<label id="POKE"><p> - -<quote> -<descrip> -<tag/Function/Write a byte to memory. -<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ -<tag/Declaration/<tt/void POKE (unsigned addr, unsigned char val);/ -<tag/Description/The function writes the value <tt/val/ to the absolute -memory address given by <tt/addr/. -<tag/Limits/<itemize> -<item>The function is actually a macro. -<item>This function depends highly on the platform and environment. -<item>Careless use will cause the program to act strange or may crash the -machine. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="PEEK" name="PEEK">, -<ref id="POKEW" name="POKEW"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>POKEW<label id="POKEW"><p> - -<quote> -<descrip> -<tag/Function/Write a word (two bytes) to memory. -<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ -<tag/Declaration/<tt/void POKEW (unsigned addr, unsigned val);/ -<tag/Description/The function writes the value <tt/val/ to the absolute -memory address given by <tt/addr/. The low byte of <tt/val/ is written to -the <tt/addr/, the high byte is written to <tt/addr+1/. -<tag/Limits/<itemize> -<item>The function is actually a macro. -<item>This function depends highly on the platform and environment. -<item>Careless use will cause the program to act strange or may crash the -machine. -<item>The order in which the two bytes are written is unspecified and may -depend of the address expression used. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="PEEK" name="PEEK">, -<ref id="POKE" name="POKE"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>SEI<label id="SEI"><p> - -<quote> -<descrip> -<tag/Function/Insert a 6502 SEI instrunction into the code. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/void SEI (void);/ -<tag/Description/The function will insert a 6502 SEI instruction into the code, -so interrupts are disabled. Note that non maskable interrupts cannot be -disabled. -<tag/Limits/<itemize> -<item>The function is actually a macro. -<item>Disabling interrupts may lead to unexpected results. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="BRK" name="BRK">, -<ref id="CLI" name="CLI"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>abort<label id="abort"><p> - -<quote> -<descrip> -<tag/Function/Terminates a program abnormally. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void abort (void);/ -<tag/Description/<tt/abort/ raises <tt/SIGABRT/, writes a termination message -on stderr, then terminates the program with an exit code of 3. -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="assert" name="assert">, -<ref id="exit" name="exit">, -<ref id="raise" name="raise"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>abs<label id="abs"><p> - -<quote> -<descrip> -<tag/Function/Returns the absolute value of an integer. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/int __fastcall__ abs (int v);/ -<tag/Description/<tt/abs/ returns the absolute value of the argument passed to -the function. -<tag/Limits/<itemize> -<item>The return value is undefined if <tt/INT_MIN/ is passed to the function. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="labs" name="labs"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>assert<label id="assert"><p> - -<quote> -<descrip> -<tag/Function/Test a condition and possibly abort. -<tag/Header/<tt/<ref id="assert.h" name="assert.h">/ -<tag/Declaration/<tt/void assert (int cond);/ -<tag/Description/<tt/assert/ is a macro that expands to a <tt/id/ -statement. If the condition evaluates t zero (false), assert prints a message -on stderr and aborts the program. -<tag/Limits/<itemize> -<item>The function is actually a macro. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="abort" name="abort">, -<ref id="exit" name="exit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>atexit<label id="atexit"><p> - -<quote> -<descrip> -<tag/Function/Register an exit function. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/int __fastcall__ atexit (void (*exitfunc) (void));/ -<tag/Description/<tt/atexit/ registers the function pointed to by -<tt/exitfunc/ as an exit function. Exit functions are called when the program -terminates, they are called in LIFO order (the last function registered is -called first). <tt/atexit/ returns zero on success and a nonzero value on -failure. -<tag/Limits/<itemize> -<item>A maximum of 5 exit functions can be registered. -<item>There is no way to unregister an exit function. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="abort" name="abort">, -<ref id="exit" name="exit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>atmos_load<label id="atmos_load"><p> - -<quote> -<descrip> -<tag/Function/Load Atmos tape. -<tag/Header/<tt/<ref id="atmos.h" name="atmos.h">/ -<tag/Declaration/<tt/void __fastcall__ atmos_load(const char* name);/ -<tag/Description/<tt/atmos_load/ reads a memory block from tape. -<tag/Availability/cc65 -<tag/See also/ -<ref id="atmos_save" name="atmos_save"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>atmos_save<label id="atmos_save"><p> - -<quote> -<descrip> -<tag/Function/Save Atmos tape. -<tag/Header/<tt/<ref id="atmos.h" name="atmos.h">/ -<tag/Declaration/<tt/void __fastcall__ atmos_save(const char* name, const void* start, const void* end);/ -<tag/Description/<tt/atmos_save/ writes a memory block to tape. -<tag/Availability/cc65 -<tag/See also/ -<ref id="atmos_load" name="atmos_load"> -<tag/Example/<verb> -atmos_save("hires", 0xa000, 0xc000); -</verb> -</descrip> -</quote> - - -<sect1>atoi<label id="atoi"><p> - -<quote> -<descrip> -<tag/Function/Convert a string to an integer. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/int __fastcall__ atoi (const char* s);/ -<tag/Description/<tt/atoi/ converts the given string into an integer. -Conversion stops as soon as any invalid character is encountered. -<tag/Limits/<itemize> -<item>There is no way to detect any conversion errors. -<item>The function does not check for an numerical overflow when converting. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="atol" name="atol">, -<ref id="itoa" name="itoa">, -<ref id="ltoa" name="ltoa">, -<ref id="ultoa" name="ultoa">, -<ref id="utoa" name="utoa"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>atol<label id="atol"><p> - -<quote> -<descrip> -<tag/Function/Convert a string to a long integer. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/long __fastcall__ atol (const char* s);/ -<tag/Description/<tt/atol/ converts the given string into a long integer. -Conversion stops as soon as any invalid character is encountered. -<tag/Limits/<itemize> -<item>There is no way to detect any conversion errors. -<item>The function does not check for an numerical overflow when converting. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="atoi" name="atoi">, -<ref id="itoa" name="itoa">, -<ref id="ltoa" name="ltoa">, -<ref id="ultoa" name="ultoa">, -<ref id="utoa" name="utoa"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>bgcolor<label id="bgcolor"><p> - -<quote> -<descrip> -<tag/Function/Set the background text color. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ bgcolor (unsigned char color);/ -<tag/Description/The function will set a new background color and return the -old (current) one. The background color is valid for the whole text output -area of the screen, not just for new text. -<tag/Limits/<itemize> -<item>Background colors are system dependent. The function may have no effect -on systems where the background color cannot be changed. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="bordercolor" name="bordercolor">, -<ref id="textcolor" name="textcolor"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>bordercolor<label id="bordercolor"><p> - -<quote> -<descrip> -<tag/Function/Set the border (frame) color. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ bordercolor (unsigned char color);/ -<tag/Description/The function will set a new border color. It returns the old -(current) border color. -<tag/Limits/<itemize> -<item>Border colors are system dependent. The function may have no effect -on systems where the border color cannot be changed. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="bgcolor" name="bgcolor">, -<ref id="textcolor" name="textcolor"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>bsearch<label id="bsearch"><p> - -<quote> -<descrip> -<tag/Function/Do a binary search in a sorted array. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void* __fastcall__ bsearch (const void* key, -const void* base, size_t n, size_t size, -int (*cmp) (const void*, const void*));/ -<tag/Description/<tt/bsearch/ searches a sorted array for a member that -matches the one pointed to by <tt/key/. <tt/base/ is the address of the array, -<tt/n/ is the number of elements, <tt/size/ the size of an element and <tt/cmp/ -the function used to compare the members against the key. The function returns -a pointer to the member found, or <tt/NULL/ if there was no match. -<tag/Limits/ -<itemize> -<item>The contents of the array must be sorted in ascending order according to -the compare function given. -<item>If there are multiple members that match the key, the function will -return one of the members. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="qsort" name="qsort"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>bzero<label id="bzero"><p> - -<quote> -<descrip> -<tag/Function/Fill a memory area with zeroes. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/void __fastcall__ bzero (void* p, size_t count);/ -<tag/Description/<tt/bzero/ fills the memory area pointed to by <tt/p/ with -zero. -<tag/Limits/ -<itemize> -<item>The function is non standard and therefore only available in non ANSI -mode. You should use <tt/<ref id="memset" name="memset">/ instead. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="_swap" name="_swap">, -<ref id="memcpy" name="memcpy">, -<ref id="memmove" name="memmove">, -<ref id="memset" name="memset">, -<tag/Example/None. -</descrip> -</quote> - - -<sect1>c64mode<label id="c64mode"><p> - -<quote> -<descrip> -<tag/Function/Switch the C128 into C64 compatible mode. -<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ -<tag/Declaration/<tt/void c64mode (void);/ -<tag/Description/The function will cause the machine to reboot into C64 mode. -<tag/Limits/<itemize> -<item>The function is specific to the C128. -<item>The function will not return to the caller. -</itemize> -<tag/Availability/C128 -<tag/Example/None. -</descrip> -</quote> - - -<sect1>calloc<label id="calloc"><p> - -<quote> -<descrip> -<tag/Function/Allocate and clear memory. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void* __fastcall__ calloc (size_t n, size_t size);/ -<tag/Description/<tt/calloc/ allocates memory for an array of <tt/n/ elements -of size <tt/size/, clears the whole block with binary zeroes and returns a -pointer to it. On error (not enough memory available), <tt/calloc/ returns -<tt/NULL/. -<tag/Limits/ -<itemize> -<item>Clearing the memory may not have the expected effect on all platforms: -pointers in the block may not be <tt/NULL/ and floating point variables may -not be zero (0.0). In other words: The "clearing" effect of this function -should be used with care for portable programs. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_heapadd" name="_heapadd">, -<ref id="_heapblocksize" name="_heapblocksize">, -<ref id="_heapmaxavail" name="_heapmaxavail">, -<ref id="_heapmemavail" name="_heapmemavail">, -<ref id="free" name="free">, -<ref id="malloc" name="malloc">, -<ref id="realloc" name="realloc"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_acptr<label id="cbm_k_acptr"><p> - -<quote> -<descrip> -<tag/Function/Input byte from serial bus -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned char cbm_k_acptr (void);/ -<tag/Description/The function returns a byte of data, which it -gets from the current TALKer on the serial bus. -In order to receive the data, the device must have previously been -sent a command to TALK and a secondary address if it needs one. -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_talk" name="cbm_k_talk">, -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_basin<label id="cbm_k_basin"><p> - -<quote> -<descrip> -<tag/Function/Input a Character from the Current Device -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned char cbm_k_basin (void);/ -<tag/Description/The function returns a character from the current input device. -Device must first have been OPENed and then designated as the input channel by the CHKIN routine. -When this function is called, the next byte of data available from the device is returned. -Exception is the routine for the keyboard device (which is the default input device). -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_open" name="cbm_k_open">, -<ref id="cbm_k_chkin" name="cbm_k_chkin"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_bsout<label id="cbm_k_bsout"><p> - -<quote> -<descrip> -<tag/Function/Output a byte -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void __fastcall__ cbm_k_bsout (unsigned char C);/ -<tag/Description/Function sends the character to the current output device. -Unless a device has been OPENed and designated as the -current output channel using the CHKOUT routine, the character is -printed to the screen, which is the default output device. If the -cassette is the current device, outputting a byte will only add it to -the buffer. No actual transmission of data will occur until the -192-byte buffer is full. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_open" name="cbm_k_open">, -<ref id="cbm_k_chkin" name="cbm_k_chkout"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_chkin<label id="cbm_k_chkin"><p> - -<quote> -<descrip> -<tag/Function/Designate a Logical File As the Current Input Channel -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_chkin (unsigned char FN);/ -<tag/Description/If you wish to -get data from any device other than the keyboard, this function must be -called after OPENing the device, before you can get a data byte with -the cbm_k_basin or cbm_k_getin routine. When called, the routine will designate -the logical file whose file number was supplied as the -current file, its device as the current device, and its secondary -address as the current secondary address. If the device on the -channel is a serial device, which requires a TALK command and -sometimes a secondary address, function will send them over the -serial bus. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_open" name="cbm_k_open">, -<ref id="cbm_k_basin" name="cbm_k_basin">, -<ref id="cbm_k_getin" name="cbm_k_getin"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_ciout<label id="cbm_k_ciout"><p> - -<quote> -<descrip> -<tag/Function/Transmit a byte over the serial bus -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void __fastcall__ cbm_k_ciout (unsigned char C);/ -<tag/Description/Purpose of this function is to send a byte of data over -the serial bus. In order for the data to be received, the serial -device must have first been commanded to LISTEN and been given a -secondary address if necessary. This routine always buffers the -current character, and defers sending it until the next byte is -buffered. When the UNLISTEN command is sent, the last byte will be -sent with an End or Identify (EOI). -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_listen" name="cbm_k_listen">, -<ref id="cbm_k_unlsn" name="cbm_k_unlsn"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_ckout<label id="cbm_k_ckout"><p> - -<quote> -<descrip> -<tag/Function/Designate a Logical File As the Current Output Channel -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_ckout (unsigned char FN);/ -<tag/Description/If you wish to -output data to any device other than the screen, this routine must be -called after OPENing the device, and before you output a data byte -with the cbm_k_bsout() function. When called, the function will designate the -logical file whose file number was supplied as the current -file, its device as the current device, and its secondary address as -the current secondary address. If the device on the channel uses the -serial bus, and therefore requires a LISTEN command and possibly a -secondary address, this information will be sent on the bus. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_bsout" name="cbm_k_bsout">, -<ref id="cbm_k_listen" name="cbm_k_listen"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_clall<label id="cbm_k_clall"><p> - -<quote> -<descrip> -<tag/Function/Close All Logical I/O Files -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void cbm_k_clall (void);/ -<tag/Description/It closes all -open files, by resetting the index into open files to -zero and restores the default I/O devices. -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_open" name="cbm_k_open">, -<ref id="cbm_k_close" name="cbm_k_close"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_close<label id="cbm_k_close"><p> - -<quote> -<descrip> -<tag/Function/Close a Logical I/O File -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void __fastcall__ cbm_k_close (unsigned char FN);/ -<tag/Description/It is used to -close a logical file after all I/O operations involving that file have -been completed. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_open" name="cbm_k_open">, -<ref id="cbm_k_clall" name="cbm_k_clall"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_clrch<label id="cbm_k_clrch"><p> - -<quote> -<descrip> -<tag/Function/Restore Current Input and Output Devices to the Default Devices -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void cbm_k_clrch (void);/ -<tag/Description/It sets the -current input device to the keyboard, and the current output device to -the screen. Also, if the current input device was formerly a serial -device, the routine sends it an UNTALK command on the serial bus, and -if a serial device was formerly the current output device, the routine -sends it an UNLISTEN command. -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_chkin" name="cbm_k_chkin">, -<ref id="cbm_k_ckout" name="cbm_k_ckout"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_getin<label id="cbm_k_getin"><p> - -<quote> -<descrip> -<tag/Function/Get One Byte from the Input Device -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned char cbm_k_getin (void);/ -<tag/Description/Function gets a character from the current input device. -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_basin" name="cbm_k_basin"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_iobase<label id="cbm_k_iobase"><p> - -<quote> -<descrip> -<tag/Function/Return Base Address of Memory-Mapped I/O Devices -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned cbm_k_iobase (void);/ -<tag/Description/This function returns the address of -the memory section where the memory mapped I/O devices are located. This -address can then be used with an offset to access the memory mapped I/O -devices in the Commodore 64. The offset is the number of locations from -the beginning of the page on which the I/O register you want is located. -This function exists to provide compatibility between the Commodore 64, -VIC-20, and future models of the Commodore 64. If the I/O locations for -a program are set by a call to this function, they should -still remain compatible with future versions of the Commodore 64, the -KERNAL and BASIC. -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ - -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_listen<label id="cbm_k_listen"><p> - -<quote> -<descrip> -<tag/Function/Command a device on the serial bus to LISTEN -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void __fastcall__ cbm_k_listen (unsigned char dev);/ -<tag/Description/This function will command a device on the serial bus to -receive data. The KERNAL routine will OR the supplied device number bit by bit -to convert it to a listen address, then transmits this data as a command on -the serial bus. The specified device will then go into listen mode, and -be ready to accept information. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_unlsn" name="cbm_k_unlsn">, -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_load<label id="cbm_k_load"><p> - -<quote> -<descrip> -<tag/Function/Load RAM from a Device -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned int __fastcall__ cbm_k_load(unsigned char flag, unsigned addr);/ -<tag/Description/This function LOADs data bytes from any input device directly into the memory. -It can also be used for a verify operation, comparing data from a device with the data already in -memory, while leaving the data stored in RAM unchanged. -The flag must be set to 0 for a LOAD operation, or 1 for a -verify, If the input device is OPENed with a secondary address (SA) of 0 -the header information from the device is ignored. In this case, the starting address for the load must be supplied. -If the device is addressed with a secondary address of 1, then the data is -loaded into memory starting at the location specified by the header. -Function returns the address of the highest RAM location loaded. -Before this function can be called, the KERNAL SETLFS, and SETNAM -routines must be called. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_save" name="cbm_k_save">, -<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, -<ref id="cbm_k_setnam" name="cbm_k_setnam"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_open<label id="cbm_k_open"><p> - -<quote> -<descrip> -<tag/Function/Open a Logical I/O File -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned char cbm_k_open (void);/ -<tag/Description/This function assigns a logical file to a device, so that it can be used for -Input/Output operations. In order to specify the logical file number, -the device number, and the secondary address if any, the cbm_k_setlfs() function must first be called. -Likewise, in order to designate the filename, the cbm_k_setnam() function must be used first. After these two -functions are called, cbm_k_open() is then called. -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_close" name="cbm_k_close">, -<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, -<ref id="cbm_k_setnam" name="cbm_k_setnam"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_readst<label id="cbm_k_readst"><p> - -<quote> -<descrip> -<tag/Function/Read status word -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned char cbm_k_readst (void);/ -<tag/Description/This function returns the current status of the I/O devices. It is usually called after new communication to an I/O device and gives information about device status, or errors that have occurred during the I/O operation. -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ - -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_save<label id="cbm_k_save"><p> - -<quote> -<descrip> -<tag/Function/Save RAM to a Device -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_save(unsigned int start, unsigned int end)/ -<tag/Description/This function saves a section of memory. The cbm_k_setlfs() and cbm_k_setnam() functions must be -used before calling this function. However, a file name is not required to -SAVE to device 1 (the Datassette(TM) recorder). Any attempt to save to -other devices without using a file name results in an error. NOTE: Device 0 (the keyboard), device 2 (RS-232), and device 3 (the screen) cannot be SAVEd to. If the attempt is made, an error occurs, and the SAVE is stopped. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_load" name="cbm_k_load">, -<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, -<ref id="cbm_k_setnam" name="cbm_k_setnam"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_setlfs<label id="cbm_k_setlfs"><p> - -<quote> -<descrip> -<tag/Function/Set up a logical file -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void __fastcall__ cbm_k_setlfs (unsigned char LFN, unsigned char DEV, unsigned char SA);/ -<tag/Description/This functions sets up the logical file by setting its number, device address, -and secondary address. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_setnam" name="cbm_k_setnam"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_setnam<label id="cbm_k_setnam"><p> - -<quote> -<descrip> -<tag/Function/Set Filename Parameters -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void __fastcall__ cbm_k_setnam (const char* Name);/ -<tag/Description/This function is used to set up the file name for the OPEN, -SAVE, or LOAD operations. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_open" name="cbm_k_open">, -<ref id="cbm_k_load" name="cbm_k_load">, -<ref id="cbm_k_save" name="cbm_k_save"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_talk<label id="cbm_k_talk"><p> - -<quote> -<descrip> -<tag/Function/Commands device to TALK -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void __fastcall__ cbm_k_talk (unsigned char dev);/ -<tag/Description/When called, it ORs the device number with the TALK code (64, $40) and sends it on the serial -bus. This commands the device to TALK. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_acptr" name="cbm_k_acptr"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cbm_k_unlsn<label id="cbm_k_unlsn"><p> - -<quote> -<descrip> -<tag/Function/Send an UNLISTEN command -<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ -<tag/Declaration/<tt/void cbm_k_unlsn (void);/ -<tag/Description/This function commands all devices on the serial bus to -stop receiving data from the host computer (i.e., UNLISTEN). Calling this -function results in an UNLISTEN command being transmitted on the serial -bus. Only devices previously commanded to LISTEN are affected. This -function is normally used after the host computer is finished sending data -to external devices. Sending the UNLISTEN commands the listening devices -to get off the serial bus so it can be used for other purposes. -<tag/Limits/<itemize> -<item> -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cbm_k_listen" name="cbm_k_listen"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cclear<label id="cclear"><p> - -<quote> -<descrip> -<tag/Function/Clear part of a line (write a given number of spaces). -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ cclear (unsigned char length);/ -<tag/Description/The function clears part of a line by writing <tt/length/ -spaces in the current text color. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cclearxy" name="cclearxy">, -<ref id="clrscr" name="clrscr"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cclearxy<label id="cclearxy"><p> - -<quote> -<descrip> -<tag/Function/Clear part of a line (write a given number of spaces) starting -at a specific screen position. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ cclearxy (unsigned char x, unsigned char y, unsigned char length);/ -<tag/Description/The function moves the cursor to a specific position, and -will then clear part of the line by writing <tt/length/ spaces in the current -text color. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cclear" name="cclear">, -<ref id="clrscr" name="clrscr"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cgetc<label id="cgetc"><p> - -<quote> -<descrip> -<tag/Function/Read a character from the keyboard. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/char cgetc (void);/ -<tag/Description/The function reads a character from the keyboard. If there is -no character available, <tt/cgetc/ waits until the user presses a key. If the -cursor is enabled by use of the <tt/cursor/ function, a blinking cursor is -displayed while waiting. -<tag/Limits/<itemize> -<item>If the system supports a keyboard buffer, <tt/cgetc/ will fetch a key -from this buffer and wait only if the buffer is empty. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cursor" name="cursor">, -<ref id="kbhit" name="kbhit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>chline<label id="chline"><p> - -<quote> -<descrip> -<tag/Function/Output a horizontal line in text mode. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ chline (unsigned char length);/ -<tag/Description/The function outputs a horizontal line with the given length -starting at the current cursor position. -<tag/Limits/<itemize> -<item>The character used to draw the horizontal line is system dependent. -If available, a line drawing character is used. Drawing a line that is partially -off screen leads to undefined behaviour. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="chlinexy" name="chlinexy">, -<ref id="cvline" name="cvline">, -<ref id="cvlinexy" name="cvlinexy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>chlinexy<label id="chlinexy"><p> - -<quote> -<descrip> -<tag/Function/Output a horizontal line at a given position in text mode. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ chlinexy (unsigned char x, unsigned char y, unsigned char length);/ -<tag/Description/The function outputs a horizontal line with the given length -starting at a given position. -<tag/Limits/<itemize> -<item>The character used to draw the horizontal line is system dependent. -If available, a line drawing character is used. Drawing a line that is partially -off screen leads to undefined behaviour. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="chline" name="chline">, -<ref id="cvline" name="cvline">, -<ref id="cvlinexy" name="cvlinexy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>clearerr<label id="clearerr"><p> - -<quote> -<descrip> -<tag/Function/Clear error and end-of-file status of a stream. -<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ -<tag/Declaration/<tt/void __fastcall__ clearerr (FILE* f);/ -<tag/Description/<tt/clearerr/ clears the error and end-of-file status -indicators for the stream <tt/f/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="feof" name="feof">, -<ref id="ferror" name="ferror"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>clock<label id="clock"><p> - -<quote> -<descrip> -<tag/Function/Determine the processor time used. -<tag/Header/<tt/<ref id="time.h" name="time.h">/ -<tag/Declaration/<tt/clock_t clock (void);/ -<tag/Description/The <tt/clock/ function returns an approximaton of processor -time used by the program. The time is returned in implementation defined -units. It can be converted to seconds by dividing by the value of the macro -<tt/CLOCKS_PER_SEC/. -<tag/Limits/<itemize> -<item>Since the machines, cc65 generated programs run on, cannot run multiple -processes, the function will actually return the time since some -implementation defined point in the past. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="time" name="time"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>clrscr<label id="clrscr"><p> - -<quote> -<descrip> -<tag/Function/Clear the text screen. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void clrscr (void);/ -<tag/Description/The function clears the text screen and moves the cursor to -the upper left corner. -<tag/Availability/cc65 -<tag/See also/ -<ref id="cclear" name="cclear">, -<ref id="cclearxy" name="cclearxy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>close<label id="close"><p> - -<quote> -<descrip> -<tag/Function/Close a file descriptor. -<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ -<tag/Declaration/<tt/int __fastcall__ close (int fd);/ -<tag/Description/The function closes the given file descriptor. It returns zero -on success and -1 on error. If an error occurs, the cause can be determined by -reading the <tt/errno/ variable. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="creat" name="creat">, -<ref id="open" name="open"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>closedir<label id="closedir"><p> - -<quote> -<descrip> -<tag/Function/Close a directory. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/int __fastcall__ closedir (DIR* dir);/ -<tag/Description/The function closes the given directory descriptor. It returns -zero on success and -1 on error. If an error occurs, the cause can be determined -by reading the <tt/errno/ variable. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="opendir" name="opendir">, -<ref id="readdir" name="readdir"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>creat<label id="creat"><p> - -<quote> -<descrip> -<tag/Function/Create a file. -<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ -<tag/Declaration/<tt/int __fastcall__ creat (const char* name, unsigned mode);/ -<tag/Description/<tt/creat/ creates a new file and returns the file descriptor -associated with it. On error, -1 is returned and an error code is stored in -<tt/errno/. -<tag/Limits/<itemize> -<item><tt/creat/ is identical to calling <tt/<ref id="open" name="open">/ with -<tt/flags/ equal to <tt/O_WRONLY | O_CREAT | O_TRUNC/. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="close" name="close">, -<ref id="open" name="open"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cprintf<label id="cprintf"><p> - -<quote> -<descrip> -<tag/Function/Formatted output to the console. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/int cprintf (const char* format, ...);/ -<tag/Description/The arguments are converted to text where necessary and -formatted according to the format string given. The resulting string is output -to the console. <tt/cprintf/ supports the same format specifiers as -<tt/printf/. <!-- <tt/<ref id="printf" name="printf">/. --> -<tag/Limits/<itemize> -<item>Like all other <tt/conio/ output functions, <tt/cprintf/ distinguishes -between <tt/\r/ and <tt/\n/. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cputc" name="cputc">, -<ref id="cputcxy" name="cputcxy">, -<ref id="cputs" name="cputs">, -<ref id="cputsxy" name="cputsxy">, -<ref id="vcprintf" name="vcprintf"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cputc<label id="cputc"><p> - -<quote> -<descrip> -<tag/Function/Output a character directly to the console. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ cputc (char c);/ -<tag/Description/Output one character to the console at the current cursor -position. -<tag/Limits/<itemize> -<item>Like all other <tt/conio/ output functions, <tt/cputc/ distinguishes -between <tt/\r/ and <tt/\n/. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cprintf" name="cprintf">, -<ref id="cputcxy" name="cputcxy">, -<ref id="cputs" name="cputs">, -<ref id="cputsxy" name="cputsxy">, -<ref id="vcprintf" name="vcprintf"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cputcxy<label id="cputcxy"><p> - -<quote> -<descrip> -<tag/Function/Output a character at a specific screen position. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ cputcxy (unsigned char x, unsigned char y, char c);/ -<tag/Description/<tt/cputcxy/ moves the cursor to the given x/y position on -the screen and outputs one character. -<tag/Limits/<itemize> -<item>Like all other <tt/conio/ output functions, <tt/cputcxy/ distinguishes -between <tt/\r/ and <tt/\n/. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cprintf" name="cprintf">, -<ref id="cputc" name="cputc">, -<ref id="cputs" name="cputs">, -<ref id="cputsxy" name="cputsxy">, -<ref id="vcprintf" name="vcprintf"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cputs<label id="cputs"><p> - -<quote> -<descrip> -<tag/Function/Output a string directly to the console. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ cputs (const char* s);/ -<tag/Description/The function outputs the given string on the console at the -current cursor position. -<tag/Limits/<itemize> -<item>Like all other <tt/conio/ output functions, <tt/cputs/ distinguishes -between <tt/\r/ and <tt/\n/. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cprintf" name="cprintf">, -<ref id="cputc" name="cputc">, -<ref id="cputcxy" name="cputcxy">, -<ref id="cputsxy" name="cputsxy">, -<ref id="vcprintf" name="vcprintf"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cputsxy<label id="cputsxy"><p> - -<quote> -<descrip> -<tag/Function/Output a string to the console at a given position. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ cputsxy (unsigned char x, unsigned char y, const char* s);/ -<tag/Description/<tt/cputsxy/ moves the cursor to the given x/y position, -and outputs the string <tt/s/. -<tag/Limits/<itemize> -<item>Like all other <tt/conio/ output functions, <tt/cputsxy/ distinguishes -between <tt/\r/ and <tt/\n/. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cprintf" name="cprintf">, -<ref id="cputc" name="cputc">, -<ref id="cputcxy" name="cputcxy">, -<ref id="cputs" name="cputs">, -<ref id="vcprintf" name="vcprintf"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cursor<label id="cursor"><p> - -<quote> -<descrip> -<tag/Function/Enable/disable a blinking cursor when waiting for keyboard input. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ cursor (unsigned char onoff);/ -<tag/Description/If the argument to the function is non zero, a blinking cursor -will be enabled when the <tt/cgetc/ function waits for input from the keyboard. -If the argument is zero, <tt/cgetc/ will wait without a blinking cursor. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cgetc" name="cgetc">, -<ref id="kbhit" name="kbhit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cvline<label id="cvline"><p> - -<quote> -<descrip> -<tag/Function/Output a vertical line in text mode. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ cvline (unsigned char length);/ -<tag/Description/The function outputs a vertical line with the given length -starting at the current cursor position. -<tag/Limits/<itemize> -<item>The character used to draw the vertical line is system dependent. -If available, a line drawing character is used. Drawing a line that is partially -off screen leads to undefined behaviour. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="chline" name="chline">, -<ref id="chlinexy" name="chlinexy">, -<ref id="cvlinexy" name="cvlinexy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>cvlinexy<label id="cvlinexy"><p> - -<quote> -<descrip> -<tag/Function/Output a vertical line at a given position in text mode. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ cvlinexy (unsigned char x, unsigned char y, unsigned char length);/ -<tag/Description/The function outputs a vertical line with the given length -starting at a given position. -<tag/Limits/<itemize> -<item>The character used to draw the vertical line is system dependent. -If available, a line drawing character is used. Drawing a line that is partially -off screen leads to undefined behaviour. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="chline" name="chline">, -<ref id="chlinexy" name="chlinexy">, -<ref id="cvline" name="cvline"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>div<label id="div"><p> - -<quote> -<descrip> -<tag/Function/Divide two ints and return quotient and remainder. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/div_t __fastcall__ div (int numer, int denom);/ -<tag/Description/<tt/div/ divides <tt/numer/ by <tt/denom/ and returns the -quotient and remainder in a <tt/div_t/ structure. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -ldiv -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_commit<label id="em_commit"><p> - -<quote> -<descrip> -<tag/Function/Commit changes into extended memory. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/void em_commit (void);/ -<tag/Description/Commit changes in the memory window to extended storage. If -the contents of the memory window have been changed, these changes may be lost -if <tt/<ref id="em_map" name="em_map">/, <tt/<ref id="em_use" name="em_use">/, -<tt/<ref id="em_copyfrom" name="em_copyfrom">/ or <tt/<ref id="em_copyto" -name="em_copyto">/ are called without calling <tt/em_commit/ first. -<tag/Limits/<itemize> -<item>Calling <tt/em_commit/ does not necessarily mean that changes to the -memory window are discarded, it does just mean that the drivers is allowed -to discard it. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -<item>The function produces undefined results if no extended memory driver is -loaded. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_load_driver" name="em_load_driver">, -<ref id="em_map" name="em_map">, -<ref id="em_use" name="em_use"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_copyfrom<label id="em_copyfrom"><p> - -<quote> -<descrip> -<tag/Function/Copy from extended into normal memory. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/void __fastcall__ em_copyfrom (const struct em_copy* copy_data);/ -<tag/Description/Copy data from extended memory into linear memory. Source and -target addresses as well as the number of bytes to transfer are specified in -the <tt/em_copy/ structure that is passed as a parameter. -<tag/Limits/<itemize> -<item>Calling <tt/em_copyfrom/ will invalidate the memory window, so if you -made any changes to the data in the window, call <tt/<ref id="em_commit" -name="em_commit">/ first, or the changes are lost. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -<item>The function produces undefined results if no extended memory driver is -loaded. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_commit" name="em_commit">, -<ref id="em_copyto" name="em_copyto">, -<ref id="em_load_driver" name="em_load_driver"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_copyto<label id="em_copyto"><p> - -<quote> -<descrip> -<tag/Function/Copy from normal into extended memory. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/void __fastcall__ em_copyto (const struct em_copy* copy_data);/ -<tag/Description/Copy data from linear into extended memory. Source and -target addresses as well as the number of bytes to transfer are specified in -the <tt/em_copy/ structure that is passed as a parameter. -<tag/Limits/<itemize> -<item>Calling <tt/em_copyto/ will invalidate the memory window, so if you -made any changes to the data in the window, call <tt/<ref id="em_commit" -name="em_commit">/ first, or the changes are lost. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -<item>The function produces undefined results if no extended memory driver is -loaded. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_commit" name="em_commit">, -<ref id="em_copyfrom" name="em_copyfrom">, -<ref id="em_load_driver" name="em_load_driver"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_install<label id="em_install"><p> - -<quote> -<descrip> -<tag/Function/Install an already loaded extended memory driver. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/unsigned char _fastcall__ em_install (void* driver);/ -<tag/Description/The function installs an already loaded extended memory driver -and returns an error code. The function may be used to install a driver linked -statically to the program. -<tag/Limits/<itemize> -<item>Not all drivers are able to detect if the supported hardware is really -present. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_load_driver" name="em_load_driver">, -<ref id="em_uninstall" name="em_uninstall">, -<ref id="em_unload" name="em_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_load_driver<label id="em_load_driver"><p> - -<quote> -<descrip> -<tag/Function/Load and initialize an extended memory driver. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/void __fastcall__ em_load_driver (const char* name);/ -<tag/Description/Load an extended memory driver into memory and initialize -it. The function returns an error code that tells if all this has been -successful. -<tag/Limits/<itemize> -<item>Not all drivers are able to detect if the supported hardware is really -present. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -<item>The driver is loaded by name, so currently you must know the type of -extended memory that should be supported. There is no autodetect capability. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_unload" name="em_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_map<label id="em_map"><p> - -<quote> -<descrip> -<tag/Function/Make a page of extended memory accessible. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/void* __fastcall__ em_map (unsigned page);/ -<tag/Description/The function maps one page of extended memory into linear -memory and returns a pointer to the page frame. Depending on the hardware -and driver, the data is either mapped into the address space or transfered -into a buffer. If you don't need the actual contents of the page (for example -because you're going to overwrite it completely), it is better to call -<tt/<ref id="em_use" name="em_use">/ instead. <tt/em_use/ will not transfer the -data if it is possible to avoid that. -<tag/Limits/<itemize> -<item>Calling <tt/em_map/ will invalidate the memory window, so if you -made any changes to the data in the window, call <tt/<ref id="em_commit" -name="em_commit">/ first, or the changes are lost. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -<item>The function produces undefined results if no extended memory driver is -loaded. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_commit" name="em_commit">, -<ref id="em_load_driver" name="em_load_driver">, -<ref id="em_use" name="em_use"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_pagecount<label id="em_pagecount"><p> - -<quote> -<descrip> -<tag/Function/Return the number of available extended memory pages. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/unsigned em_pagecount (void);/ -<tag/Description/The function returns the size of the extended memory supported -by the driver in 256 byte pages. -<tag/Limits/<itemize> -<item>The function returns zero if no extended memory driver is loaded. -<item>The function may return zero if the supported hardware was not detected. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_load_driver" name="em_load_driver"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_uninstall<label id="em_uninstall"><p> - -<quote> -<descrip> -<tag/Function/Uninstall an already loaded extended memory driver. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/unsigned char em_uninstall (void);/ -<tag/Description/The function uninstalls an already loaded extended memory -driver but doesn't remove it from memory. -<tag/Limits/<itemize> -<item>If the driver has been loaded using <tt/<ref id="em_load_driver" -name="em_load_driver">/, <tt/<ref id="em_unload" name="em_unload">/ -should be used instead of <tt/em_uninstall/ so the driver is also removed -from memory. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_install" name="em_install">, -<ref id="em_load_driver" name="em_load_driver">, -<ref id="em_unload" name="em_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_unload<label id="em_unload"><p> - -<quote> -<descrip> -<tag/Function/Unload an extended memory driver. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/unsigned char em_unload (void);/ -<tag/Description/The function unloads a loaded extended memory driver and -frees all memory allocated for the driver. -<tag/Limits/<itemize> -<item>The function does nothing if no driver is loaded. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_load_driver" name="em_load_driver"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>em_use<label id="em_use"><p> - -<quote> -<descrip> -<tag/Function/Prepare an extended memory page for use. -<tag/Header/<tt/<ref id="em.h" name="em.h">/ -<tag/Declaration/<tt/void* __fastcall__ em_use (unsigned page);/ -<tag/Description/The function maps one page of extended memory into linear -memory and returns a pointer to the page frame. This function is similar to -<tt/<ref id="em_map" name="em_map">/, but will not transfer data into the -actual memory window in the assumption that the existing data is wrong or -will get overwritten. -<tag/Limits/<itemize> -<item>Calling <tt/em_use/ will invalidate the memory window, so if you -made any changes to the data in the window, call <tt/<ref id="em_commit" -name="em_commit">/ first, or the changes are lost. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -<item>The function produces undefined results if no extended memory driver is -loaded. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="em_commit" name="em_commit">, -<ref id="em_load_driver" name="em_load_driver">, -<ref id="em_map" name="em_map"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>exit<label id="exit"><p> - -<quote> -<descrip> -<tag/Function/Terminate the program. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void __fastcall__ exit (int status);/ -<tag/Description/<tt/exit/ terminates the program. The argument specifies the -return code of the program. Before termination, all files are closed, buffered -output is written and any functions registered with <tt/<ref id="atexit" -name="atexit">/ are called. Common values for status are <tt/EXIT_SUCCESS/ and -<tt/EXIT_FAILURE/ which are also defined in <tt/<ref id="stdlib.h" -name="stdlib.h">/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>It depends on the host machine if the program return code can be -evaluated or is ignored. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="abort" name="abort">, -<ref id="exit" name="exit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>exec<label id="exec"><p> - -<quote> -<descrip> -<tag/Function/Execute a program file. -<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ -<tag/Declaration/<tt/int __fastcall__ exec (const char* progname, const char* cmdline);/ -<tag/Description/<tt/exec/ replaces the currently running program by a new one. -Calling <tt/exec()/ is identical to calling <tt/<ref id="exit" name="exit()">/, -then loading and starting the program named in the first argument, passing -the command line specified as second argument. Instead of an empty string, -a <tt/NULL/ pointer may be passed as second parameter. -On success, the function does not return. On failure, -1 is returned and -<tt/errno/ contains an error code. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>On most platforms, the function needs to copy a small stub loader to -some memory area outside the program space. This may collide with other -programs. See the platform specific docs on this. -<item>Because it is necessary to terminate the running program before the -memory can be reused to load the new one, there is a high chance that the -function may not be able to return on errors. -<item>The command line is passed to the new program in the same way as cc65 -programs expect the command line. If the new program is not a cc65 generated -program, it may not be able to read it. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="exit" name="exit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>fast<label id="fast"><p> - -<quote> -<descrip> -<tag/Function/Switch the C128 into 2MHz mode. -<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ -<tag/Declaration/<tt/void fast (void);/ -<tag/Description/The function will switch the clock of the C128 to 2MHz. This -will nearly double the speed compared to slow mode. -<tag/Limits/<itemize> -<item>The function is specific to the C128. -<item>2MHz clock will not work in 40 column mode. -</itemize> -<tag/Availability/C128 -<tag/See also/ -<ref id="slow" name="slow">, -<ref id="toggle_videomode" name="toggle_videomode">, -<ref id="videomode" name="videomode"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>feof<label id="feof"><p> - -<quote> -<descrip> -<tag/Function/Return the end-of-file indicator of a stream. -<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ -<tag/Declaration/<tt/int __fastcall__ feof (FILE* f);/ -<tag/Description/<tt/feof/ tests the end-of-file indicator ofthe stream -<tt/f/, and returns a non zero value if it is set. -<tag/Limits/<itemize> -<item>The indicator is set only after a read past the end of a file is -attempted. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="feof" name="clearerr">, -<ref id="ferror" name="ferror"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>ferror<label id="ferror"><p> - -<quote> -<descrip> -<tag/Function/Return the error indicator of a stream. -<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ -<tag/Declaration/<tt/int __fastcall__ ferror (FILE* f);/ -<tag/Description/<tt/ferror/ tests the error indicator of the stream -<tt/f/, and returns a non zero value if it is set. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="feof" name="clearerr">, -<ref id="ferror" name="feof"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>fileno<label id="fileno"><p> - -<quote> -<descrip> -<tag/Function/Return the file handle used by a stream. -<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ -<tag/Declaration/<tt/int __fastcall__ fileno (FILE* f);/ -<tag/Description/The <tt/fileno/ function returns the file handle used -internally by a C stream. This file handle (an integer) can be used as a -handle for the POSIX input/output functions. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -<item>Mixing C file I/O functions and POSIX file I/O functions for the same -file may have unpredictable results. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="creat" name="creat">, -<ref id="open" name="open"> <!-- , --> -<!-- <ref id="read" name="read">, --> -<!-- <ref id="write" name="write"> --> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>free<label id="free"><p> - -<quote> -<descrip> -<tag/Function/Free a block of dynamic memory. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void __fastcall__ free (void* block);/ -<tag/Description/Free a block of dynamic memory previously allocated with -<tt/<ref id="malloc" name="malloc">/, <tt/<ref id="calloc" name="calloc">/ -or <tt/<ref id="realloc" name="realloc">/. As an exception, if the passed -pointer is <tt/NULL/, no action is performed. -<tag/Limits/ -<itemize> -<item>Passing an already free'd block to <tt/free/ again will cause undefined -behaviour and may crash your program. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_heapadd" name="_heapadd">, -<ref id="_heapblocksize" name="_heapblocksize">, -<ref id="_heapmaxavail" name="_heapmaxavail">, -<ref id="_heapmemavail" name="_heapmemavail">, -<ref id="calloc" name="calloc">, -<ref id="malloc" name="malloc">, -<ref id="realloc" name="realloc"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>get_ostype<label id="get_ostype"><p> - -<quote> -<descrip> -<tag/Function/The function returns the operating system, the program runs on. -<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">, -<ref id="atari.h" name="atari.h">, <ref id="c64.h" name="c64.h">/ -<tag/Declaration/<tt/unsigned char get_ostype (void);/ -<tag/Description/<tt/get_ostype/ is machine dependent and does not exist for -all supported targets. If it exists, it returns a number that identifies the -operating system or machine type, the program runs on. The machine dependent -header files define constants that can be used to check the return code. -<tag/Limits/<itemize> -<item>The function does not exist on all platforms. -<item>The return codes are platform dependent. -</itemize> -<tag/Availability/cc65 (not all platforms) -<tag/Example/None. -</descrip> -</quote> - - -<sect1>getcpu<label id="getcpu"><p> - -<quote> -<descrip> -<tag/Function/Determine on which CPU the program is running. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/unsigned char getcpu (void);/ -<tag/Description/The function checks on which CPU the code is running. It -returns one of the constants<itemize> -<item><tt/CPU_6502/ -<item><tt/CPU_65C02/ -<item><tt/CPU_65816/ -</itemize> -<tag/Limits/<itemize> -<item>Other, more exotic CPU types are not disinguished. -</itemize> -<tag/Availability/cc65 -<tag/Example/None. -</descrip> -</quote> - - -<sect1>getenv<label id="getenv"><p> - -<quote> -<descrip> -<tag/Function/Return a value from the environment. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/char* __fastcall__ getenv (const char* name);/ -<tag/Description/The function searches the environment for an entry that -matches <tt/name/ and returns its value. The environment consists of a list -of strings in the form <tt/name=value/. If there is no match, <tt/getenv/ -returns <tt/NULL/. -<tag/Limits/<itemize> -<item>What exactly is stored in the environment depends on the machine the -program is running on. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/Example/None. -</descrip> -</quote> - - -<sect1>getopt<label id="getopt"><p> - -<quote> -<descrip> -<tag/Function/Parse command line options. -<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ -<tag/Declaration/<tt/int __fastcall__ getopt (int argc, char* const* argv, -const char* optstring);/ -<tag/Description/The function parses command line arguments, <tt/argc/ and -<tt/argv/ are the argument count and array passed to <tt/main/. <tt/optstring/ -is a string that contains command line option characters. If a character in -<tt/optstring/ is followed by a colon, the option requires an argument. An -option on the command line is recognized if it is one of the option characters -preceeded by a '-'. -<tt/getopt/ must be called repeatedly. It will return each option character -found on the command line and <tt/EOF/ (-1) if there is no other option. An -option argument is placed in <tt/optarg/, the index of the next element on the -command line to be processed is placed in <tt/optind/. -<tag/Limits/<itemize> -<item>The implementation will not reorder options. A non option on the command -line will terminate option processing. All remaining arguments are not -recognized as options, even if the start with a '-' character. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX.2 -<tag/Example/None. -</descrip> -</quote> - - -<sect1>gotox<label id="gotox"><p> - -<quote> -<descrip> -<tag/Function/Move the text mode cursor to a new X position. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ gotox (unsigned char x);/ -<tag/Description/The function moves the text mode cursor to the specified X -position while leaving the Y position untouched. The leftmost position on the -screen has the coordinate 0. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -<item>Invalid values for the X position (out of screen coordinates) may -lead to undefined behaviour. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="gotoy" name="gotoy">, -<ref id="gotoxy" name="gotoxy">, -<ref id="wherex" name="wherex">, -<ref id="wherey" name="wherey"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>gotoxy<label id="gotoxy"><p> - -<quote> -<descrip> -<tag/Function/Move the text mode cursor to a new position. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ gotoxy (unsigned char x, unsigned char y);/ -<tag/Description/The function moves the text mode cursor to the specified -position. The leftmost position on the screen has the X coordinate 0, the -topmost line has the Y coordinate 0. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -<item>Invalid values for any of both coordinates (out of screen positions) may -lead to undefined behaviour. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="gotox" name="gotox">, -<ref id="gotoy" name="gotoy">, -<ref id="wherex" name="wherex">, -<ref id="wherey" name="wherey"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>gotoy<label id="gotoy"><p> - -<quote> -<descrip> -<tag/Function/Move the text mode cursor to a new Y position. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ gotoy (unsigned char x);/ -<tag/Description/The function moves the text mode cursor to the specified Y -position while leaving the X position untouched. The uppermost position on the -screen has the coordinate 0. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -<item>Invalid values for the Y position (out of screen coordinates) may lead -to undefined behaviour. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="gotox" name="gotox">, -<ref id="gotoxy" name="gotoxy">, -<ref id="wherex" name="wherex">, -<ref id="wherey" name="wherey"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isalnum<label id="isalnum"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a letter or digit. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isalnum (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a letter or digit. The return value is zero if the character is anything -else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing -the macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isalpha<label id="isalpha"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a letter. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isalpha (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a letter. The return value is zero if the character is anything else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isascii<label id="isascii"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is in the ASCII (0..127) range. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isascii (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is in the range 0..127 (the range of valid ASCII characters) and zero if not. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isblank<label id="isblank"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a space or tab. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isblank (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a space or tab character. The return value is zero if the character is -anything else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>iscntrl<label id="iscntrl"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a control character. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ iscntrl (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a control character. The return value is zero if the character is anything -else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isdigit<label id="isdigit"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a digit. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isdigit (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a digit. The return value is zero if the character is anything else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isgraph<label id="isgraph"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a printable character (except -space). -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isgraph (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a printable character with the exception of space. The return value is zero -if the character is anything else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>islower<label id="islower"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a lower case letter. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ islower (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a lower case letter. The return value is zero if the character is anything -else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isprint<label id="isprint"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a printable character. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isprint (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a printable character (this includes the space character). The return value -is zero if the character is anything else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>ispunct<label id="ispunct"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a printable character but not a -space or an alphanumeric character. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ ispunct (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a printable character, but not a space or anything alphanumeric. The return -value is zero if the character is anything else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isspace<label id="isspace"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a a white-space character. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isspace (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a white space character. The return value is zero if the character is -anything else. The standard white space characters are: space, formfeed ('\f'), -newline ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab -('\v'). -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isupper" name="isupper">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isupper<label id="isupper"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is an upper case letter. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isupper (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is an upper case letter. The return value is zero if the character is anything -else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isxdigit" name="isxdigit"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>isxdigit<label id="isxdigit"><p> - -<quote> -<descrip> -<tag/Function/Check if a given character is a hexadecimal digit. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ isxdigit (int c);/ -<tag/Description/The function returns a non zero value if the given argument -is a hexadecimal digit (0..9, a..f and A..F). The return value is zero if the -character is anything else. -<tag/Limits/<itemize> -<item>When compiling with <tt/-Os/ the function is actually a macro. The -inline sequence generated by the macro will not work correctly for values -outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of -this range. The non inline function may be accessed by <tt/#undef/'ing the -macro. -<item>When compiling without <tt/-Os/, the function is only available as -fastcall function, so it may only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="isalnum" name="isalnum">, -<ref id="isalpha" name="isalpha">, -<ref id="isascii" name="isascii">, -<ref id="isblank" name="isblank">, -<ref id="iscntrl" name="iscntrl">, -<ref id="isdigit" name="isdigit">, -<ref id="isgraph" name="isgraph">, -<ref id="islower" name="islower">, -<ref id="isprint" name="isprint">, -<ref id="ispunct" name="ispunct">, -<ref id="isspace" name="isspace">, -<ref id="isupper" name="isupper"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>itoa<label id="itoa"><p> - -<quote> -<descrip> -<tag/Function/Convert an integer into a string. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/char* __fastcall__ itoa (int val, char* buf, int radix);/ -<tag/Description/<tt/itoa/ converts the integer <tt/val/ into a string using -<tt/radix/ as the base. -<tag/Limits/<itemize> -<item>There are no provisions to prevent a buffer overflow. -<item>If <tt/val/ contains <tt/INT_MIN/, the behaviour is undefined. -<item>The function is non standard, so it is not available in strict ANSI mode. -You should probably use <tt/sprintf/ instead. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="atoi" name="atoi">, -<ref id="atol" name="atol">, -<ref id="ltoa" name="ltoa">, -<ref id="ultoa" name="ultoa">, -<ref id="utoa" name="utoa"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>joy_count<label id="joy_count"><p> - -<quote> -<descrip> -<tag/Function/Return the number of joysticks supported by the current driver. -<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ -<tag/Declaration/<tt/unsigned char joy_count (void);/ -<tag/Description/The function returns a the number of joysticks supported -by the current joystick driver. -<tag/Limits/<itemize> -<item>A joystick driver must be loaded using <ref id="joy_load_driver" -name="joy_load_driver"> before calling this function. -<item>The function returns the number of joysticks supported by the driver. -There's no way to check for the number of actually connected joysticks. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="joy_load_driver" name="joy_load_driver">, -<ref id="joy_read" name="joy_read"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>joy_install<label id="joy_install"><p> - -<quote> -<descrip> -<tag/Function/Install an already loaded driver and return an error code. -<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ joy_install (void* driver);/ -<tag/Description/The function installs a driver that was already loaded into -memory (or linked statically to the program). It returns an error code -(<tt/JOY_ERR_OK/ in case of success). -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="joy_load_driver" name="joy_load_driver">, -<ref id="joy_uninstall" name="joy_uninstall">, -<ref id="joy_unload" name="joy_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>joy_load_driver<label id="joy_load_driver"><p> - -<quote> -<descrip> -<tag/Function/Load a driver from disk and install it. -<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ joy_load_driver (const char* driver);/ -<tag/Description/The function loads a driver with the given name from disk -and installs it. An error code is returned, which is <tt/JOY_ERR_OK/ if the -driver was successfully loaded and installed. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="joy_install" name="joy_install">, -<ref id="joy_uninstall" name="joy_uninstall">, -<ref id="joy_unload" name="joy_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>joy_read<label id="joy_read"><p> - -<quote> -<descrip> -<tag/Function/Read the status of a joystick. -<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ joy_read (unsigned char joystick);/ -<tag/Description/The function reads the status bits for a joystick. The number -of the joystick is passed as parameter. The result may be examined by using one -of the <tt/JOY_xxx/ macros from <ref id="joystick.h" name="joystick.h">. -<tag/Limits/<itemize> -<item>A joystick driver must be loaded using <ref id="joy_load_driver" -name="joy_load_driver"> before calling this function. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="joy_count" name="joy_count">, -<ref id="joy_load_driver" name="joy_load_driver">, -<ref id="joy_unload" name="joy_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>joy_uninstall<label id="joy_uninstall"><p> - -<quote> -<descrip> -<tag/Function/Uninstall the current joystick driver. -<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ -<tag/Declaration/<tt/unsigned char joy_uninstall (void);/ -<tag/Description/The function uninstalls the currently installed joystick -driver. It does not remove the driver from memory. The function returns an -error code, which is <tt/JOY_ERR_OK/ if the driver was successfully uninstalled. -<tag/Limits/<itemize> -<item>A joystick driver must be installed using <ref id="joy_install" -name="joy_install"> before calling this function. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="joy_install" name="joy_install">, -<ref id="joy_load_driver" name="joy_load_driver">, -<ref id="joy_unload" name="joy_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>joy_unload<label id="joy_unload"><p> - -<quote> -<descrip> -<tag/Function/Uninstall, then unload the current joystick driver. -<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ -<tag/Declaration/<tt/unsigned char joy_unload (void);/ -<tag/Description/The function uninstalls the currently installed joystick -driver and removes it from memory. An error code is returned, which is -<tt/JOY_ERR_OK/ if the driver was successfully uninstalled. -<tag/Limits/<itemize> -<item>A joystick driver must be loaded using <ref id="joy_load_driver" -name="joy_load_driver"> before calling this function. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="joy_load_driver" name="joy_load_driver"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>kbhit<label id="kbhit"><p> - -<quote> -<descrip> -<tag/Function/Check if there's a key waiting in the keyboard buffer. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/unsigned char kbhit (void);/ -<tag/Description/The function returns a value of zero if there is no character -waiting to be read from the keyboard. It returns non zero otherwise. -<tag/Limits/<itemize> -<item>If the system does not support a keyboard buffer (most systems -do), the function is rather useless. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cgetc" name="cgetc">, -<ref id="cursor" name="cursor"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>labs<label id="labs"><p> - -<quote> -<descrip> -<tag/Function/Returns the absolute value of a long integer. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/long __fastcall__ labs (long v);/ -<tag/Description/<tt/labs/ returns the absolute value of the argument passed to -the function. -<tag/Limits/<itemize> -<item>The return value is undefined if <tt/LONG_MIN/ is passed to the function. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="abs" name="abs"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>ltoa<label id="ltoa"><p> - -<quote> -<descrip> -<tag/Function/Convert a long integer into a string. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/char* __fastcall__ ltoa (long val, char* buf, int radix);/ -<tag/Description/<tt/itoa/ converts the long integer <tt/val/ into a string -using <tt/radix/ as the base. -<tag/Limits/<itemize> -<item>There are no provisions to prevent a buffer overflow. -<item>If <tt/val/ contains <tt/LONG_MIN/, the behaviour is undefined. -<item>The function is non standard, so it is not available in strict ANSI mode. -You should probably use <tt/sprintf/ instead. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="atoi" name="atoi">, -<ref id="atol" name="atol">, -<ref id="itoa" name="itoa">, -<ref id="ultoa" name="ultoa">, -<ref id="utoa" name="utoa"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>localeconv<label id="localeconv"><p> - -<quote> -<descrip> -<tag/Function/Returns a pointer to the current locale structure. -<tag/Header/<tt/<ref id="locale.h" name="locale.h">/ -<tag/Declaration/<tt/struct lconv* localeconv (void);/ -<tag/Description/<tt/localeconv/ returns a pointer to the current locale -structure. -<tag/Limits/<itemize> -<item>cc65 supports only the "C" locale, so even after setting a new locale -using <tt/<ref id="setlocale" name="setlocale">/, the structure returned will -always be the same. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="setlocale" name="setlocale"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>longjmp<label id="longjmp"><p> - -<quote> -<descrip> -<tag/Function/Non local goto. -<tag/Header/<tt/<ref id="setjmp.h" name="setjmp.h">/ -<tag/Declaration/<tt/void __fastcall__ longjmp (jmp_buf buf, int retval);/ -<tag/Description/The <tt/longjmp/ function restores a program context from the -data in <tt/buf/, which must have been set by a preceeding call to -<tt/<ref id="setjmp" name="setjmp">/. Program execution continues as if the -call to <tt/<ref id="setjmp" name="setjmp">/ has just returned the value -<tt/retval/. -<tag/Limits/ -<itemize> -<item>If the parameter <tt/retval/ is zero, the function will behave as if it -was called with a value of one. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="setjmp" name="setjmp"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>malloc<label id="malloc"><p> - -<quote> -<descrip> -<tag/Function/Allocate dynamic memory. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void* __fastcall__ malloc (size_t size);/ -<tag/Description/<tt/malloc/ allocates size bytes on the heap and returns a -pointer to the allocated memory block. On error (not enough memory available), -<tt/malloc/ returns <tt/NULL/. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_heapadd" name="_heapadd">, -<ref id="_heapblocksize" name="_heapblocksize">, -<ref id="_heapmaxavail" name="_heapmaxavail">, -<ref id="_heapmemavail" name="_heapmemavail">, -<ref id="calloc" name="calloc">, -<ref id="free" name="free">, -<ref id="realloc" name="realloc">, -<ref id="strdup" name="strdup"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>memchr<label id="memchr"><p> - -<quote> -<descrip> -<tag/Function/Search for a character in a block of raw memory. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/void* __fastcall__ strchr (const void* mem, int c, size_t count);/ -<tag/Description/The <tt/memchr/ function locates the first occurrence of <tt/c/ -(converted to a char) in the block of raw memory string pointed to by <tt/mem/ -that is of size <tt/count/. Upon completion, the function returns a pointer to -the character found, or a null pointer if the character was not found. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strchr" name="strchr"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>memcmp<label id="memcmp"><p> - -<quote> -<descrip> -<tag/Function/Compare two memory areas. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/int __fastcall__ memcmp (const void* p1, const void* p2, size_t count);/ -<tag/Description/<tt/memcmp/ compares <tt/count/ bytes from the memory area -pointed to by <tt/p1/ into the memory area pointed to by <tt/p2/. It returns a value that is less than -zero if <tt/p1/ is less than <tt/p2/, zero if <tt/p1/ is the same as <tt/p2/, -and a value greater than zero if <tt/p1/ is greater than <tt/p2/. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcmp" name="strcmp">, -<ref id="memmove" name="memmove">, -<ref id="memset" name="memset"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>memcpy<label id="memcpy"><p> - -<quote> -<descrip> -<tag/Function/Copy a memory area. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/void* __fastcall__ memcpy (void* dest, const void* src, size_t count);/ -<tag/Description/<tt/memcpy/ copies <tt/count/ bytes from the memory area -pointed to by <tt/src/ into the memory area pointed to by <tt/dest/. It returns -<tt/dest/. -<tag/Limits/ -<itemize> -<item>The result is undefined if the memory areas do overlap. Use -<tt/<ref id="memmove" name="memmove">/ to copy overlapping memory areas. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_swap" name="_swap">, -<ref id="memmove" name="memmove">, -<ref id="memset" name="memset"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>memmove<label id="memmove"><p> - -<quote> -<descrip> -<tag/Function/Copy a memory area. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/void* __fastcall__ memmove (void* dest, const void* src, size_t count);/ -<tag/Description/<tt/memmove/ copies <tt/count/ bytes from the memory area -pointed to by <tt/src/ into the memory area pointed to by <tt/dest/. It returns -<tt/dest/. -<tag/Limits/ -<itemize> -<item>While <tt/memmove/ allows the memory areas to overlap, it has some -additional overhead compared to <tt/<ref id="memcpy" name="memcpy">/. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_swap" name="_swap">, -<ref id="memcpy" name="memcpy">, -<ref id="memset" name="memset"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>memset<label id="memset"><p> - -<quote> -<descrip> -<tag/Function/Fill a memory area. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/void* __fastcall__ memset (void* p, int val, size_t count);/ -<tag/Description/<tt/memset/ fills the memory area pointed to by <tt/p/ with -the value <tt/val/. The function returns <tt/p/. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_swap" name="_swap">, -<ref id="bzero" name="bzero">, -<ref id="memcpy" name="memcpy">, -<ref id="memmove" name="memmove"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mod_free<label id="mod_free"><p> - -<quote> -<descrip> -<tag/Function/Free a relocatable module. -<tag/Header/<tt/<ref id="modload.h" name="modload.h">/ -<tag/Declaration/<tt/void __fastcall__ mod_free (void* module);/ -<tag/Description/The function will free a module loaded into memory by use of -the <tt/<ref id="mod_load" name="mod_load">/ function. -<tag/Limits/<itemize> -<item>The pointer passed as parameter is the pointer to the module memory, -not the pointer to the control structure. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mod_load" name="mod_load"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mod_load<label id="mod_load"><p> - -<quote> -<descrip> -<tag/Function/Load a relocatable module. -<tag/Header/<tt/<ref id="modload.h" name="modload.h">/ -<tag/Declaration/<tt/unsigned char mod_load (struct mod_ctrl* ctrl);/ -<tag/Description/The function will load a code module into memory and relocate -it. The function will return an error code. If <tt/MLOAD_OK/ is returned, the -outgoing fields in the passed <tt/mod_ctrl/ struct contain information about -the module just loaded. Possible error codes are: -<itemize> -<item><tt/MLOAD_OK/ - Module load successful -<item><tt/MLOAD_ERR_READ/ - Read error -<item><tt/MLOAD_ERR_HDR/ - Header error -<item><tt/MLOAD_ERR_OS/ - Wrong operating system -<item><tt/MLOAD_ERR_FMT/ - Data format error -<item><tt/MLOAD_ERR_MEM/ - Not enough memory -</itemize> -<tag/Limits/<itemize> -<item>The <htmlurl url="ld65.html" name="ld65"> linker is needed to create -relocatable o65 modules for use with this function. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mod_free" name="mod_free"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_setbox<label id="mouse_setbox"><p> - -<quote> -<descrip> -<tag/Function/Specify a bounding box for the mouse cursor. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/void __fastcall__ mouse_setbox (const struct mouse_box* box);/ -<tag/Description/The function allows to set a bounding box for mouse movement. -<tag/Limits/<itemize> -<item>The function does not check if the mouse cursor is currently within the -given rectangle. Placing the mouse cursor within the bounding box is the -responsibility of the programmer. -<item>While the bounding box may be larger than the actual screen size, the -standard mouse cursor draw routines may fail to set the cursor to coordinates -outside of the screen area. Depending on the platform, you may have to supply -your own mouse cursor routines. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_getbox" name="mouse_getbox">, -<ref id="mouse_move" name="mouse_move"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_getbox<label id="mouse_getbox"><p> - -<quote> -<descrip> -<tag/Function/Return the current bounding box for the mouse cursor. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/void __fastcall__ mouse_getbox (struct mouse_box* box);/ -<tag/Description/The function queries the current bounding box for mouse -movement. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_move" name="mouse_move">, -<ref id="mouse_setbox" name="mouse_setbox"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_buttons<label id="mouse_buttons"><p> - -<quote> -<descrip> -<tag/Function/Return a bit mask encoding the state of the mouse buttons. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/unsigned char mouse_buttons (void);/ -<tag/Description/The function returns a bit mask that encodes the state of the -mouse buttons. You may use the <tt/MOUSE_BTN_XXX/ flags to decode the function -return value. -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_info" name="mouse_info">, -<ref id="mouse_pos" name="mouse_pos"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_geterrormsg<label id="mouse_geterrormsg"><p> - -<quote> -<descrip> -<tag/Function/Return a readable error message for an error code. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/const char* __fastcall__ mouse_geterrormsg (unsigned char -code);/ -<tag/Description/The function returns an error message (in english) for the -error code passed parameter. -<tag/Limits/<itemize> -<item>The function will return "Unknown error" for invalid error codes. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_load_driver" name="mouse_load_driver">, -<ref id="mouse_uninstall" name="mouse_uninstall">, -<ref id="mouse_unload" name="mouse_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_hide<label id="mouse_hide"><p> - -<quote> -<descrip> -<tag/Function/Hide the mouse pointer. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/void mouse_hide (void);/ -<tag/Description/The function hides the mouse pointer. It manages a counter -that is shared between <tt/<ref id="mouse_show" name="mouse_show">/ and -<tt/mouse_hide/ so that every call call to <tt/mouse_hide/ must be followed by -a call to <tt/<ref id="mouse_show" name="mouse_show">/ to make the mouse cursor -visible. -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_show" name="mouse_show"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_info<label id="mouse_info"><p> - -<quote> -<descrip> -<tag/Function/Return the state of the mouse buttons and the position of the -mouse. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/void __fastcall__ mouse_info (struct mouse_info* info);/ -<tag/Description/The function returns the state of the mouse buttons and the -position of the mouse in the <tt/mouse_info/ structure passed as parameter. -<tag/Limits/<itemize> -<item>The <tt/mouse_info/ struct is a superset of the <tt/mouse_pos/ struct, -so if you just need the mouse position, call <tt/<ref id="mouse_pos" -name="mouse_pos">/ instead. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_buttons" name="mouse_buttons">, -<ref id="mouse_pos" name="mouse_pos"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_install<label id="mouse_install"><p> - -<quote> -<descrip> -<tag/Function/Install an already loaded mouse driver. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ mouse_install (const struct -mouse_callbacks* c, void* driver);/ -<tag/Description/The function installs an already loaded mouse driver and -returns an error code. The <tt/mouse_callbacks/ structure passed as first -parameter contains pointers to routines needed to move or hide/show the mouse -pointer. Defaults for these routines are supplied by the library, so if you -can live with these defaults (which are platform specific), just pass a -pointer to <tt/mouse_def_callbacks/. The function may be used to install a -driver linked statically to the program. -<tag/Limits/<itemize> -<item>Not all drivers are able to detect if the supported hardware is really -present. -<item>After installing a driver, the mouse cursor is hidden. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_load_driver" name="mouse_load_driver">, -<ref id="mouse_uninstall" name="mouse_uninstall">, -<ref id="mouse_unload" name="mouse_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_ioctl<label id="mouse_ioctl"><p> - -<quote> -<descrip> -<tag/Function/Call the driver specific ioctl function. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ mouse_ioctl (unsigned char code, void* data);/ -<tag/Description/The function calls the IOCTL entry in the mouse driver, -which is driver specific. The <tt/code/ parameter will choose between -different IOCTL functions, and the <tt/data/ depends on code. The -function returns an error code. The purpose of this function is to allow -for driver specific extensions. See the documentation for a specific mouse -driver for supported ioctl calls. -<tag/Limits/<itemize> -<item>Calling this function is non portable, because each driver may -implement different ioctl calls (or none at all). -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_load_driver<label id="mouse_load_driver"><p> - -<quote> -<descrip> -<tag/Function/Load and initialize a mouse driver. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ mouse_load_driver (const struct -mouse_callbacks* c, const char* driver);/ -<tag/Description/Load a mouse driver into memory and initialize it. The -function returns an error code that tells if the call has been successful. The -<tt/mouse_callbacks/ structure passed as first parameter contains pointers to -routines needed to move or hide/show the mouse pointer. Defaults for these -routines are supplied by the library, so if you can live with these defaults -(which are platform specific), just pass a pointer to <tt/mouse_def_callbacks/. -<tag/Limits/<itemize> -<item>The driver is loaded by name, so currently you must know the type of -mouse that should be supported. There is no autodetect capability. -<item>Not all drivers are able to detect if the supported hardware is really -present. -<item>After installing a driver, the mouse cursor is hidden. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_install" name="mouse_install">, -<ref id="mouse_uninstall" name="mouse_uninstall">, -<ref id="mouse_unload" name="mouse_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_move<label id="mouse_move"><p> - -<quote> -<descrip> -<tag/Function/Move the mouse cursor to a specific position. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/void __fastcall__ mouse_move (int x, int y);/ -<tag/Description/The function updates the mouse position. If the mouse cursor -is visible, it is shown at the new position. -<tag/Limits/<itemize> -<item>The function does not check if the new position is within the bounding -box specified with <tt/<ref id="mouse_setbox" name="mouse_setbox">/. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_getbox" name="mouse_getbox">, -<ref id="mouse_setbox" name="mouse_setbox"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_pos<label id="mouse_pos"><p> - -<quote> -<descrip> -<tag/Function/Return the position of the mouse. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/void __fastcall__ mouse_pos (struct mouse_pos* pos);/ -<tag/Description/The function returns the position of the mouse in the -<tt/mouse_pos/ structure passed as parameter. -<tag/Limits/<itemize> -<item>The <tt/mouse_pos/ struct is a subset of the <tt/mouse_info/ struct, -so if you do also need the mouse buttons, call <tt/<ref id="mouse_info" -name="mouse_info">/ instead. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_buttons" name="mouse_buttons">, -<ref id="mouse_info" name="mouse_info"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_show<label id="mouse_show"><p> - -<quote> -<descrip> -<tag/Function/Show the mouse pointer. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/void mouse_show (void);/ -<tag/Description/The function shows the mouse pointer. It manages a counter -that is shared between <tt/<ref id="mouse_hide" name="mouse_hide">/ and -<tt/mouse_show/. The mouse cursor is visible if there was one more call to -<tt/mouse_show/ than to <tt/<ref id="mouse_hide" name="mouse_hide">/. -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_hide" name="mouse_hide"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_uninstall<label id="mouse_uninstall"><p> - -<quote> -<descrip> -<tag/Function/Uninstall an already loaded mouse driver. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/unsigned char mouse_uninstall (void);/ -<tag/Description/The function uninstalls an already loaded mouse driver but -don't removes it from memory. -<tag/Limits/<itemize> -<item>If the driver has been loaded using <tt/<ref id="mouse_load_driver" -name="mouse_load_driver">/, <tt/<ref id="mouse_unload" name="mouse_unload">/ -should be used instead of <tt/mouse_uninstall/ so the driver is also removed -from memory. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_install" name="mouse_install">, -<ref id="mouse_load_driver" name="mouse_load_driver">, -<ref id="mouse_unload" name="mouse_unload"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>mouse_unload<label id="mouse_unload"><p> - -<quote> -<descrip> -<tag/Function/Unload a mouse driver. -<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ mouse_unload (void);/ -<tag/Description/The function unloads a loaded mouse driver and frees all -memory allocated for the driver. -<tag/Limits/<itemize> -<item>The function does nothing if no driver is loaded. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="mouse_install" name="mouse_install">, -<ref id="mouse_load_driver" name="mouse_load_driver">, -<ref id="mouse_uninstall" name="mouse_uninstall"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>offsetof<label id="offsetof"><p> - -<quote> -<descrip> -<tag/Function/Calculate the offset of a struct or union member. -<tag/Header/<tt/<ref id="stddef.h" name="stddef.h">/ -<tag/Declaration/<tt/size_t offsetof (type, member);/ -<tag/Description/<tt/offsetof/ calculates the address offset of a <tt/struct/ -or <tt/union/ member. -<tag/Limits/<itemize> -<item>The function is actually a macro. -</itemize> -<tag/Availability/ISO 9899 -<tag/Example/None. -</descrip> -</quote> - - -<sect1>open<label id="open"><p> - -<quote> -<descrip> -<tag/Function/Open and possibly create a file. -<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ -<tag/Declaration/<tt/int open (const char* name, int flags, ...);/ -<tag/Description/<tt/open/ opens a file and returns the file descriptor -associated with it. On error, -1 is returned and an error code is stored in -<tt/errno/. Several flags may be passed to <tt/open/ that change the behaviour. -<tag/Limits/<itemize> -<item>POSIX specifies an additional <tt/mode/ argument that may be passed to -open, which is used as the permission mask when a new file is created. While -cc65 allows to pass this argument, it is ignored. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="close" name="close">, -<ref id="creat" name="creat"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>opendir<label id="opendir"><p> - -<quote> -<descrip> -<tag/Function/Open a directory. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/DIR* __fastcall__ opendir (const char* name);/ -<tag/Description/<tt/opendir/ opens a directory and returns the direcory -descriptor associated with it. On error, NULL is returned and an error code is -stored in <tt/errno/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="closedir" name="closedir">, -<ref id="readdir" name="readdir"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>peekbsys<label id="peekbsys"><p> - -<quote> -<descrip> -<tag/Function/Read one byte from a location in the system bank. -<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, -<tt/<ref id="cbm510.h" name="cbm510.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ peekbsys (unsigned addr);/ -<tag/Description/<tt/peekbsys/ reads one byte from the given address in the -system bank (bank 15) of the CBM PET-II machines and returns it. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>This function may be a macro depending on the compiler options. The -actual function is accessible by #undef'ing the macro. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="PEEK" name="PEEK">, -<ref id="PEEKW" name="PEEKW">, -<ref id="peekwsys" name="peekwsys">, -<ref id="pokebsys" name="pokebsys">, -<ref id="pokewsys" name="pokewsys"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>peekwsys<label id="peekwsys"><p> - -<quote> -<descrip> -<tag/Function/Read one word from a location in the system bank. -<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, -<tt/<ref id="cbm510.h" name="cbm510.h">/ -<tag/Declaration/<tt/unsigned __fastcall__ peekwsys (unsigned addr);/ -<tag/Description/<tt/peekwsys/ reads one word from the given address in the -system bank (bank 15) of the CBM PET-II machines and returns it. Following -the usual 6502 conventions, the low byte is read from <tt/addr/, and the -high byte is read from <tt/addr+1/. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The order in which the two bytes are read is undefined. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="PEEK" name="PEEK">, -<ref id="PEEKW" name="PEEKW">, -<ref id="peekbsys" name="peekbsys">, -<ref id="pokebsys" name="pokebsys">, -<ref id="pokewsys" name="pokewsys"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>perror<label id="perror"><p> - -<quote> -<descrip> -<tag/Function/Print an error message for the error in <tt/errno/. -<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ -<tag/Declaration/<tt/void __fastcall__ perror (const char* s);/ -<tag/Description/<tt/perror/ prints an error message to <tt/stderr/. If <tt/s/ -is not <tt/NULL/ and not an empty string, it is printed followed by a colon and -a blank. Then the error message for the current contents of <tt/errno/ is -printed followed by a newline. The message output is the same as returned by -<tt/<ref id="strerror" name="strerror">/ with an argument of <tt/errno/. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_poserror" name="_poserror">, -<ref id="strerror" name="strerror"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>pokebsys<label id="pokebsys"><p> - -<quote> -<descrip> -<tag/Function/Write one byte to a location in the system bank. -<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, -<tt/<ref id="cbm510.h" name="cbm510.h">/ -<tag/Declaration/<tt/void __fastcall__ pokebsys (unsigned addr, unsigned char val);/ -<tag/Description/<tt/pokebsys/ writes one byte to the given address in the -system bank (bank 15) of the CBM PET-II machines. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="POKE" name="POKE">, -<ref id="POKEW" name="POKEW">, -<ref id="peekbsys" name="peekbsys">, -<ref id="peekwsys" name="peekwsys">, -<ref id="pokewsys" name="pokewsys"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>pokewsys<label id="pokewsys"><p> - -<quote> -<descrip> -<tag/Function/Write one word to a location in the system bank. -<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, -<tt/<ref id="cbm510.h" name="cbm510.h">/ -<tag/Declaration/<tt/void __fastcall__ pokewsys (unsigned addr, unsigned val);/ -<tag/Description/<tt/pokewsys/ writes one word to the given address in the -system bank (bank 15) of the CBM PET-II machines. Following the usual 6502 -conventions, the low byte of <tt/val/ is written to <tt/addr/, and the -high byte is written to <tt/addr+1/. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The order in which the two bytes are written is undefined. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="POKE" name="POKE">, -<ref id="POKEW" name="POKEW">, -<ref id="peekbsys" name="peekbsys">, -<ref id="peekwsys" name="peekwsys">, -<ref id="pokebsys" name="pokebsys"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>qsort<label id="qsort"><p> - -<quote> -<descrip> -<tag/Function/Sort an array. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void __fastcall__ qsort (void* base, size_t count, -size_t size, int (*compare) (const void*, const void*));/ -<tag/Description/<tt/qsort/ sorts an array according to a given compare -function <tt/compare/. <tt/base/ is the address of the array, <tt/count/ -is the number of elements, <tt/size/ the size of an element and <tt/compare/ -the function used to compare the members. -<tag/Limits/ -<itemize> -<item>If there are multiple members with the same key, the order after calling -the function is undefined. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="bsearch" name="bsearch"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>raise<label id="raise"><p> - -<quote> -<descrip> -<tag/Function/Send a signal to the executing program. -<tag/Header/<tt/<ref id="signal.h" name="signal.h">/ -<tag/Declaration/<tt/int __fastcall__ raise (int sig);/ -<tag/Description/<tt/raise/ sends the given signal to the program. If the -program has installed a signal handler for the signal, this signal handler -will be executed. If no handler has been installed, the default action for -the raised signal will be taken. The function returns zero on success, -nonzero otherwise. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="abort" name="abort">, -<ref id="signal" name="signal"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>rand<label id="rand"><p> - -<quote> -<descrip> -<tag/Function/Return a pseudo random number. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/int rand (void);/ -<tag/Description/The function returns a pseudo random number -between 0 and <tt/RAND_MAX/ (exclusive). -<tag/Limits/<itemize> -<item>Without using <tt><ref id="srand" name="srand"></tt>, always the same -flow of numbers is generated. -<item>On startup, the function behaves as if <ref id="srand" name="srand"> -had been used with an argument of 1. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_randomize" name="_randomize">, -<ref id="srand" name="srand"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>readdir<label id="readdir"><p> - -<quote> -<descrip> -<tag/Function/Read a directory. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/struct dirent* __fastcall__ readdir (DIR* dir);/ -<tag/Description/<tt/readdir/ reads the next directory entry from the directory -stream pointed to by <tt/dir/. It stores the data in a <tt/dirent/ structure -and returns a pointer to it. If the end of directory is reached, or an error -occurs, NULL is returned. In case of errors, an error code is stored into -<tt/errno/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The returned pointer may point to a statically allocated instance of -<tt/struct dirent/, so it may get overwritten by subsequent calls to -<tt/readdir/. -<item>On several platforms, namely the CBMs and the Atari, the disk drives get -confused when opening/closing files between directory reads. So for example a -program that reads the list of files on a disk, and after each call to -<tt/readdir/, opens the file to process it, will fail.<newline> -Possible solutions are reading the directory into memory before processing the -file list, or to reset the directory by seeking to the correct position after -opening/closing a file: -<verb> - seekdir (DIR, telldir (DIR)); -</verb> -Platforms known to work without problems are: Apple. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="closedir" name="closedir">, -<ref id="opendir" name="opendir"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>realloc<label id="realloc"><p> - -<quote> -<descrip> -<tag/Function/Change the size of an allocated memory block. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void* __fastcall__ realloc (void* block, size_t size);/ -<tag/Description/<tt/realloc/ changes the size of the memory block pointed to -by <tt/block/ to <tt/size/ bytes. If <tt/block/ is <tt/NULL/, <tt/realloc/ -behaves as if <tt/malloc/ had been called. If <tt/size/ is zero, <tt/realloc/ -behaves as if <tt/free/ had been called. On error (not enough memory -available), <tt/realloc/ returns <tt/NULL/. -<tag/Limits/ -<itemize> -<item>The part of the memory block that is returned will have its contents -unchanged. -<item>This function is somewhat dangerous to use. Be careful to save the -pointer you're passing somewhere else, otherwise -<tscreen><verb> - ptr = realloc (ptr, size); -</verb></tscreen> -will loose your only copy of <tt/ptr/ if <tt/realloc/ returns <tt/NULL/. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_heapadd" name="_heapadd">, -<ref id="_heapblocksize" name="_heapblocksize">, -<ref id="_heapmaxavail" name="_heapmaxavail">, -<ref id="_heapmemavail" name="_heapmemavail">, -<ref id="calloc" name="calloc">, -<ref id="free" name="free">, -<ref id="realloc" name="realloc"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>remove<label id="remove"><p> - -<quote> -<descrip> -<tag/Function/Delete a file. -<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ -<tag/Declaration/<tt/int __fastcall__ remove (const char* name);/ -<tag/Description/<tt/remove/ deletes the file with the given name. On success, -zero is returned. On error, -1 is returned and <tt/errno/ is set to an error -code describing the reason for the failure. -<tag/Limits/ -<itemize> -<item>This function is not available on all cc65 targets (depends on the -availability of file I/O). -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="rename" name="rename">, -<ref id="unlink" name="unlink"> -<tag/Example/ -<verb> -#include <stdio.h> - -#define FILENAME "helloworld" - -if (remove (FILENAME) == 0) { - printf ("We deleted %s successfully\n", FILENAME); -} else { - printf ("There was a problem deleting %s\n", FILENAME); -} -</verb> -</descrip> -</quote> - - -<sect1>rename<label id="rename"><p> - -<quote> -<descrip> -<tag/Function/Rename a file. -<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ -<tag/Declaration/<tt/int __fastcall__ rename (const char* oldname, const char* newname);/ -<tag/Description/<tt/rename/ renames a file (gives it a new name). On success, -zero is returned. On error, -1 is returned and <tt/errno/ is set to an error -code describing the reason for the failure. -<tag/Limits/ -<itemize> -<item>This function is not available on all cc65 targets (depends on the -capabilities of the storage devices). -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="remove" name="remove"> -<tag/Example/ -<verb> -#include <stdio.h> - -#define OLDNAME "textfile.txt" -#define NEWNAME "textfile.bak" - -if (rename (OLDNAME, NEWNAME) == 0) { - printf ("Renamed %s to %s\n", OLDNAME, NEWNAME); -} else { - printf ("Error renaming %s to %s\n", OLDNAME, NEWNAME); -} -</verb> -</descrip> -</quote> - - -<sect1>reset_brk<label id="reset_brk"><p> - -<quote> -<descrip> -<tag/Function/Resets the break vector to its original value. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/void reset_brk (void);/ -<tag/Description/<tt/reset_brk/ resets the break vector to the value it had -before a call to <tt/set_brk/. -<tag/Limits/ -<itemize> -<item>Since <tt/<ref id="set_brk" name="set_brk">/ installs an exit handler, -it is not strictly necessary to call this function as part of the cleanup when -the program ends. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="reset_irq" name="reset_irq">, -<ref id="set_brk" name="set_brk">, -<ref id="set_irq" name="set_irq"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>reset_irq<label id="reset_irq"><p> - -<quote> -<descrip> -<tag/Function/Resets the C level interrupt request vector. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/void reset_irq (void);/ -<tag/Description/<tt/reset_irq/ resets the C level interrupt request vector. -<tag/Limits/ -<itemize> -<item>The original IRQ vector is restored on program termination even without -calling this function. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="reset_brk" name="reset_brk">, -<ref id="set_brk" name="set_brk">, -<ref id="set_irq" name="set_irq"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>revers<label id="revers"><p> - -<quote> -<descrip> -<tag/Function/Control revers character display. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ revers (unsigned char onoff);/ -<tag/Description/If the argument is non zero, the function enables reverse -character display. If the argument is zero, reverse character display is -switched off. The old value of the setting is returned. -<tag/Limits/<itemize> -<item>The function may not be supported by the hardware, in which case -the call is ignored. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="textcolor" name="textcolor"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>rewinddir<label id="rewinddir"><p> - -<quote> -<descrip> -<tag/Function/Reset a directory stream. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/void __fastcall__ rewinddir (DIR* dir);/ -<tag/Description/<tt/rewinddir/ sets the position of the directory stream -pointed to by <tt/dir/ to the start of the directory. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="seekdir" name="seekdir">, -<ref id="telldir" name="telldir"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>screensize<label id="screensize"><p> - -<quote> -<descrip> -<tag/Function/Return the dimensions of the text mode screen. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/void __fastcall__ screensize (unsigned char* x, unsigned char* y);/ -<tag/Description/The function returns the dimensions of the text mode screen. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="gotox" name="gotox">, -<ref id="gotoxy" name="gotoxy">, -<ref id="gotoy" name="gotoy">, -<ref id="wherex" name="wherex">, -<ref id="wherey" name="wherey"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>seekdir<label id="seekdir"><p> - -<quote> -<descrip> -<tag/Function/Set the position of a directory stream. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/void __fastcall__ seekdir (DIR* dir, long offset);/ -<tag/Description/<tt/seekdir/ sets the position of the directory stream -pointed to by <tt/dir/ to the value given in <tt/offset/, which should be a -value returned by <tt/<ref id="telldir" name="telldir">/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="rewinddir" name="rewinddir">, -<ref id="telldir" name="telldir"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>ser_close<label id="ser_close"><p> - -<quote> -<descrip> -<tag/Function/Close the port and disable interrupts -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char ser_close (void);/ -<tag/Description/Close the port by clearing buffers and disable interrupts. -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/ -<verb> -#include <serial.h> - -static void initialize(){ - struct ser_params params = { - SER_BAUD_9600, - SER_BITS_8, - SER_STOP_1, - SER_PAR_MARK, - SER_HS_NONE - }; - ser_install(lynx_comlynx); // This will activate the ComLynx - CLI(); - ser_open(&params); -} -</verb> -</descrip> -</quote> - - -<sect1>ser_get<label id="ser_get"><p> - -<quote> -<descrip> -<tag/Function/Read a character from serial port. -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ ser_get (char* b);/ -<tag/Description/Get a character from the serial port. If no characters are -available, the function will return SER_ERR_NO_DATA, so this is not a fatal -error. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/ -Wait for a character to be available from a serial port. -<verb> -char ch; -while (ser_get(&ch) == SER_ERR_NO_DATA) - ; -</verb> -</descrip> -</quote> - - -<sect1>ser_install<label id="ser_install"><p> - -<quote> -<descrip> -<tag/Function/Install an already loaded driver and return an error code. -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ ser_install (void* driver);/ -<tag/Description/The function installs a driver that was already loaded into -memory (or linked statically to the program). It returns an error code -(<tt/SER_ERR_OK/ in case of success). -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="ser_load_driver" name="ser_load_driver">, -<ref id="ser_uninstall" name="ser_uninstall">, -<ref id="ser_unload" name="ser_unload"> -<tag/Example/<verb> -ser_install(lynx_comlynx); //Include the driver statically instead of loading it. -</verb> -</descrip> -</quote> - - -<sect1>ser_ioctl<label id="ser_ioctl"><p> - -<quote> -<descrip> -<tag/Function/Platform dependent code extensions. -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned __fastcall__ ser_ioctl (unsigned char code, void* data);/ -<tag/Description/Some platforms have extra serial functions that are not -supported by standard serial driver functions. You can extend the driver to support -this extra functionality bt using ser_ioctl functions. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>These functions are not easily portable to other cc65 platforms. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/None -</descrip> -</quote> - -<sect1>ser_load_driver<label id="ser_load_driver"><p> - -<quote> -<descrip> -<tag/Function/Load and install a serial driver. -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ ser_load_driver (const char *name);/ -<tag/Description/Load and install the driver by name. -Will just load the driver and check if loading was successful. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>ser_open<label id="ser_open"><p> - -<quote> -<descrip> -<tag/Function/Open the port by setting the port parameters and enable interrupts -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ ser_open (const struct ser_params* params);/ -<tag/Description/Open the port by setting the port parameters and enable interrupts. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/ -<verb> -#include <serial.h> - -static void initialize(){ - struct ser_params params = { - SER_BAUD_9600, - SER_BITS_8, - SER_STOP_1, - SER_PAR_MARK, - SER_HS_NONE - }; - ser_install(lynx_comlynx); // This will activate the ComLynx - CLI(); - ser_open(&params); -} -</verb> -</descrip> -</quote> - - -<sect1>ser_put<label id="ser_put"><p> - -<quote> -<descrip> -<tag/Function/Write a character to a serial port. -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ ser_put (char b);/ -<tag/Description/Send a character via the serial port. There is a transmit -buffer, but transmitting is not done via interrupt. The function returns -SER_ERR_OVERFLOW if there is no space left in the transmit buffer. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/ -<verb> -ser_put('A'); -</verb> -</descrip> -</quote> - - -<sect1>ser_status<label id="ser_status"><p> - -<quote> -<descrip> -<tag/Function/Return the serial port status. -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ ser_status (unsigned char* status);/ -<tag/Description/Return the serial port status. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/None -</descrip> -</quote> - - -<sect1>ser_uninstall<label id="ser_uninstall"><p> - -<quote> -<descrip> -<tag/Function/Uninstall the currently loaded driver but do not unload it. -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char ser_uninstall (void);/ -<tag/Description/Uninstall the currently loaded driver but do not unload it. -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/None. -</descrip> -</quote> - -<sect1>ser_unload<label id="ser_unload"><p> - -<quote> -<descrip> -<tag/Function/Uninstall, then unload the currently loaded driver. -<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ -<tag/Declaration/<tt/unsigned char ser_unload (void);/ -<tag/Description/Uninstall, then unload the currently loaded driver. -<tag/Availability/cc65 -<tag/See also/Other serial functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>set_brk<label id="set_brk"><p> - -<quote> -<descrip> -<tag/Function/Set the break vector to a user function. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/void __fastcall__ set_brk (brk_handler func);/ -<tag/Description/<tt/set_brk/ allows a user program to handle breaks within the -program code by letting the vector point to a user written C function. The -runtime library installs a small stub that saves the registers into global -variables that may be accessed (and changed) by the break handler. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The stub saves the zero page registers used by the C runtime and switches -to a small break handler stack. This means that it is safe to execute C code, -even if C code was interrupted. Be careful however not to use too many local -variables, and do not enable stack checks for the handler function or any other -function called from it. -<item>The <tt/brk_pc/ variable points to the <tt/BRK/ instruction. If you want -the continue with the interrupted code, you have to adjust <tt/brk_pc/, -otherwise the <tt/BRK/ instruction will get executed over and over again. -<item>Since <tt/set_brk/ installs an exit handler, it is not strictly necessary -to call <tt/<ref id="reset_brk" name="reset_brk">/ as part of the cleanup when -the program terminates. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="reset_brk" name="reset_brk"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>set_irq<label id="set_irq"><p> - -<quote> -<descrip> -<tag/Function/Set the C level interrupt request vector to the given address. -<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ -<tag/Declaration/<tt/void __fastcall__ set_irq (irq_handler f, void *stack_addr, size_t stack_size);/ -<tag/Description/<tt/set_irq/ allows a user program to handle interrupt requests -(IRQs) within the program code by letting the vector point to a user written C -function. The runtime library installs a small stub that saves the zero page -registers used by the C runtime before calling the handler function and restores -them after the handler function returns. Additionally the stub temporarily switches -the C runtime stack to the stack area provided as parameter. If the handler function -was set up to handle a "private", "exclusive" interrupt request source it must -return the value <tt/IRQ_HANDLED/ if and only if it has verified that the current -interrupt request actually stems from that source. In all other cases it must return -the value <tt/IRQ_NOT_HANDLED/. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The stub saves the registers and zero page locations used by the C runtime -and switches to the provided stack area. As a consequence, there is some -runtime overhead, but it it is safe to execute C code, even if other C code -was interrupted. Be careful however not to call C library functions, and do not -enable stack checks for the handler function or any other function called from -it. -<item>The interrupt vector is reset on function termination, so it's not -strictly necessary to call <tt/<ref id="reset_irq" name="reset_irq">/ as part -of the cleanup when the program terminates. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="reset_brk" name="reset_brk">, -<ref id="reset_irq" name="reset_irq">, -<ref id="set_brk" name="set_brk"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>setjmp<label id="setjmp"><p> - -<quote> -<descrip> -<tag/Function/Save the context for use with <tt/longjmp/. -<tag/Header/<tt/<ref id="setjmp.h" name="setjmp.h">/ -<tag/Declaration/<tt/int __fastcall__ setjmp (jmp_buf buf);/ -<tag/Description/The <tt/setjmp/ function saves the current context in <tt/buf/ -for subsequent use by the <tt/<ref id="longjmp" name="longjmp">/ function and -returns zero. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item><tt/setjmp/ is actually a macro as required by the ISO standard. -<item><tt/setjmp/ will not save the signal context. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="longjmp" name="longjmp"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>setlocale<label id="setlocale"><p> - -<quote> -<descrip> -<tag/Function/Selects a locale. -<tag/Header/<tt/<ref id="locale.h" name="locale.h">/ -<tag/Declaration/<tt/char* __fastcall__ setlocale (int category, const char* locale);/ -<tag/Description/<tt/setlocale/ sets or queries the program's locale. -<tag/Limits/ -<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>cc65 supports only the "C" locale, so calling this function to set a -different locale has no effect. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="localeconv" name="localeconv">, -<ref id="strcoll" name="strcoll"> -<ref id="strxfrm" name="strxfrm"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>signal<label id="signal"><p> - -<quote> -<descrip> -<tag/Function/Install a signal handler. -<tag/Header/<tt/<ref id="signal.h" name="signal.h">/ -<tag/Declaration/<tt/__sigfunc __fastcall__ signal (int sig, __sigfunc func);/ -<tag/Description/<tt/signal/ installs a handler for the given signal. The -handler may either be a user supplied function, or one of the predefined -signal handlers <tt/SIG_IGN/ or <tt/SIG_DFL/. The function returns the -previous value if the signal , or the special function vector SIG_ERR in -case of an error. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="abort" name="abort">, -<ref id="raise" name="raise"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>sleep<label id="sleep"><p> - -<quote> -<descrip> -<tag/Function/Sleep for a specified amount of time. -<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ -<tag/Declaration/<tt/void __fastcall__ sleep (unsigned seconds);/ -<tag/Description/The function will return after the specified number of -seconds have elapsed. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/Example/None. -</descrip> -</quote> - - -<sect1>slow<label id="slow"><p> - -<quote> -<descrip> -<tag/Function/Switch the C128 into 1MHz mode. -<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ -<tag/Declaration/<tt/void slow (void);/ -<tag/Description/The function will switch the clock of the C128 to 1MHz. This -will halve the speed compared to fast mode. -<tag/Limits/<itemize> -<item>The function is specific to the C128. -</itemize> -<tag/Availability/C128 -<tag/See also/ -<ref id="fast" name="fast">, -<ref id="toggle_videomode" name="toggle_videomode">, -<ref id="videomode" name="videomode"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>srand<label id="srand"><p> - -<quote> -<descrip> -<tag/Function/Initialize the pseudo random number generator. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/void __fastcall__ srand (unsigned seed);/ -<tag/Description/The function initializes the random number generator using -the given seed. On program startup, the generator behaves as if <tt/srand/ has -been called with an argument of 1. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_randomize" name="_randomize">, -<ref id="rand" name="rand"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strcasecmp<label id="strcasecmp"><p> - -<quote> -<descrip> -<tag/Function/Compare two strings case insensitive. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/int __fastcall__ strcasecmp (const char* s1, const char* s2);/ -<tag/Description/The <tt/strcasecmp/ function compares the two strings passed -as parameters without case sensitivity. It returns a value that is less than -zero if <tt/s1/ is less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, -and a value greater than zero if <tt/s1/ is greater than <tt/s2/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The function is not available in strict ANSI mode. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="strcmp" name="strcmp">, -<ref id="strcoll" name="strcoll">, -<ref id="stricmp" name="stricmp">, -<ref id="strncmp" name="strncmp">, -<ref id="strxfrm" name="strxfrm"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strcat<label id="strcat"><p> - -<quote> -<descrip> -<tag/Function/Concatentate two strings. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strcat (char* s1, const char* s2);/ -<tag/Description/The <tt/strcat/ function appends a copy of the string -pointed to by s2 (including the terminating null byte) to the end of the -string pointed to by s1. The initial byte of s2 overwrites the null byte at -the end of s1. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>If copying takes place between objects that overlap, the behaviour -is undefined. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcpy" name="strcpy">, -<ref id="strncat" name="strncat">, -<ref id="strncpy" name="strncpy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strchr<label id="strchr"><p> - -<quote> -<descrip> -<tag/Function/Search for a character in a string. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strchr (const char* s, int c);/ -<tag/Description/The <tt/strchr/ function locates the first occurrence of <tt/c/ -(converted to a char) in the string pointed to by <tt/s/. The terminating null -byte is considered to be part of the string. Upon completion, the function -returns a pointer to the byte, or a null pointer if the byte was not found. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="memchr" name="memchr">, -<ref id="strrchr" name="strrchr"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strcmp<label id="strcmp"><p> - -<quote> -<descrip> -<tag/Function/Compare two strings. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/int __fastcall__ strcmp (const char* s1, const char* s2);/ -<tag/Description/The <tt/strcmp/ function compares the two strings passed as -parameters. It returns a value that is less than zero if <tt/s1/ is less than -<tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a value greater than zero -if <tt/s1/ is greater than <tt/s2/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcasecmp" name="strcasecmp">, -<ref id="strcoll" name="strcoll">, -<ref id="stricmp" name="stricmp">, -<ref id="strncmp" name="strncmp"> -<ref id="strxfrm" name="strxfrm"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strcoll<label id="strcoll"><p> - -<quote> -<descrip> -<tag/Function/Compare two strings. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/int __fastcall__ strcoll (const char* s1, const char* s2);/ -<tag/Description/The <tt/strcoll/ function compares the two strings passed as -parameters, according to the collating sequence set by <tt/<ref id="setlocale" -name="setlocale">/. It returns a value that is less than zero if <tt/s1/ is -less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a value greater -than zero if <tt/s1/ is greater than <tt/s2/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="setlocale" name="setlocale">, -<ref id="strcasecmp" name="strcasecmp">, -<ref id="strcmp" name="strcmp">, -<ref id="stricmp" name="stricmp">, -<ref id="strncmp" name="strncmp">, -<ref id="strxfrm" name="strxfrm"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strcpy<label id="strcpy"><p> - -<quote> -<descrip> -<tag/Function/Copy a string. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strcpy (char* s1, const char* s2);/ -<tag/Description/The <tt/strcpy/ function copies the string pointed to by -<tt/s2/ (including the terminating null byte) into the array pointed to by -<tt/s1/. The function will always return <tt/s1/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>If copying takes place between objects that overlap, the behaviour -is undefined. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcat" name="strcat">, -<ref id="strncat" name="strncat">, -<ref id="strncpy" name="strncpy"> -<tag/Example/ -<verb> -#include <string.h> - -static char hello[14]; - -strcpy (hello, "Hello world!\n"); -</verb> -</descrip> -</quote> - - -<sect1>strcspn<label id="strcspn"><p> - -<quote> -<descrip> -<tag/Function/Compute the length of a substring. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/size_t __fastcall__ strcspn (const char* s, const char* set);/ -<tag/Description/The <tt/strcspn/ function computes and returns the length of -the substring pointed to by <tt/s/ which does <em>not</em> consist of -characters contained in the string <tt/set/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strspn" name="strspn">, -<ref id="strstr" name="strstr">, -<ref id="strtok" name="strtok"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strdup<label id="strdup"><p> - -<quote> -<descrip> -<tag/Function/Allocate a copy of a string on the heap. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strdup (const char* s);/ -<tag/Description/<tt/strdup/ allocates a memory block on the heap, big enough -to hold a copy of <tt/s/ including the terminating zero. If the allocation -fails, <tt/NULL/ is returned, otherwise <tt/s/ is copied into the allocated -memory block, and a pointer to the block is returned. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>It is up to the caller to free the allocated memory block. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="free" name="free">, -<ref id="malloc" name="malloc"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strerror<label id="strerror"><p> - -<quote> -<descrip> -<tag/Function/Return a string describing an error code. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strerror (int errcode);/ -<tag/Description/The <tt/strerror/ function returns a string describing the -given error code. If an invalid error code is passed, the string "Unknown -error" is returned, and <tt/errno/ is set to <tt/EINVAL/. In all other cases, -<tt/errno/ is left untouched. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>While the return type of the function is a <tt/char*/, the returned -string must not be modified by the caller! -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="_stroserror" name="_stroserror"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>stricmp<label id="stricmp"><p> - -<quote> -<descrip> -<tag/Function/Compare two strings case insensitive. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/int __fastcall__ stricmp (const char* s1, const char* s2);/ -<tag/Description/The <tt/stricmp/ function compares the two strings passed as -parameters without case sensitivity. It returns a value that is less than zero -if <tt/s1/ is less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a -value greater than zero if <tt/s1/ is greater than <tt/s2/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The function is not available in strict ANSI mode. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="strcasecmp" name="strcasecmp">, -<ref id="strcmp" name="strcmp">, -<ref id="strcoll" name="strcoll">, -<ref id="strncmp" name="strncmp">, -<ref id="strxfrm" name="strxfrm"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strlen<label id="strlen"><p> - -<quote> -<descrip> -<tag/Function/Return the length of a string. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/size_t __fastcall__ strlen (const char* s);/ -<tag/Description/The <tt/strlen/ function computes the number of bytes in the -string to which s points, not including the terminating null byte. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>When compiling with <tt/-Os/ (inline known standard functions), the -function does not work correctly for strings with more than 255 characters. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcpy" name="strcpy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strlower<label id="strlower"><p> - -<quote> -<descrip> -<tag/Function/Make a string lower case. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strlower (char* s);/ -<tag/Description/The <tt/strlower/ function will apply the <tt/tolower/ -function to each character of a string. The function will always return <tt/s/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The function prototype is unavailable when compiling in strict ANSI mode. -<item>An alias name for this function is <tt/strlwr/. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="strupper" name="strupper">, -<ref id="tolower" name="tolower"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strlwr<label id="strlwr"><p> - -<quote> -See <tt/strlower/. -</quote> - - -<sect1>strncat<label id="strncat"><p> - -<quote> -<descrip> -<tag/Function/Concatentate two strings. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strncat (char* s1, const char* s2, size_t n);/ -<tag/Description/The <tt/strncat/ function appends not more than n characters -of the string pointed to by s2 to the end of the string pointed to by s1. The -terminating null character at the end of s1 is overwritten. A terminating null -character is appended to the result, even if not all of s2 is appended to s1. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>If copying takes place between objects that overlap, the behaviour -is undefined. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcpy" name="strcpy">, -<ref id="strncat" name="strncat">, -<ref id="strncpy" name="strncpy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strncmp<label id="strncmp"><p> - -<quote> -<descrip> -<tag/Function/Compare two strings. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/int __fastcall__ strncmp (const char* s1, const char* s2, size_t count);/ -<tag/Description/The <tt/strncmp/ function compares not more than <tt/count/ -characters of the two strings passed as parameters. It returns a value that is -less than zero if the first <tt/count/ characters of <tt/s1/ are less than -<tt/s2/, zero if they are identical, and a value greater than zero they are -greater. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcasecmp" name="strcasecmp">, -<ref id="strcmp" name="strcmp">, -<ref id="strcoll" name="strcoll">, -<ref id="stricmp" name="stricmp">, -<ref id="strxfrm" name="strxfrm"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strncpy<label id="strncpy"><p> - -<quote> -<descrip> -<tag/Function/Copy part of a string. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strcpy (char* s1, const char* s2, size_t n);/ -<tag/Description/The <tt/strncpy/ function copies not more than n bytes from -the array pointed to by <tt/s2/ to the array pointed to by <tt/s1/. If the array -pointed to by <tt/s2/ is a string that is shorter than n bytes, null bytes are -appended to the copy in the array pointed to by <tt/s1/, until <tt/n/ bytes are -written. The function will always return <tt/s1/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. If there is no null byte in the first <tt/n/ -bytes of the array pointed to by <tt/s2/, the result is not null-terminated. -<item>If copying takes place between objects that overlap, the behaviour is -undefined. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcat" name="strcat">, -<ref id="strcpy" name="strcpy">, -<ref id="strncat" name="strncat"> -<tag/Example/ -<verb> -#include <string.h> - -static char hello[6]; - -strcpy (hello, "Hello world!\n", sizeof (hello) - 1); -hello[5] = '\0'; -</verb> -</descrip> -</quote> - - -<sect1>strrchr<label id="strrchr"><p> - -<quote> -<descrip> -<tag/Function/Search for a character in a string. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strrchr (const char* s, int c);/ -<tag/Description/The <tt/strrchr/ function locates the last occurrence of <tt/c/ -(converted to a char) in the string pointed to by <tt/s/. The terminating null -byte is considered to be part of the string. Upon completion, the function -returns a pointer to the byte, or a null pointer if the byte was not found. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strchr" name="strchr"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strspn<label id="strspn"><p> - -<quote> -<descrip> -<tag/Function/Compute the length of a substring. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/size_t __fastcall__ strspn (const char* s, const char* set);/ -<tag/Description/The <tt/strspn/ function computes and returns the length of -the substring pointed to by <tt/s/ which does consist only of characters -contained in the string <tt/set/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcspn" name="strcspn">, -<ref id="strstr" name="strstr"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strstr<label id="strstr"><p> - -<quote> -<descrip> -<tag/Function/Find a substring. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strstr (const char* str, const char* substr);/ -<tag/Description/<tt/strstr/ searches for the first occurance of the string -<tt/substr/ within <tt/str/. If found, it returns a pointer to the copy, -otherwise it returns <tt/NULL/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcspn" name="strcspn">, -<ref id="strspn" name="strspn"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strtok<label id="strtok"><p> - -<quote> -<descrip> -<tag/Function/Break a string into tokens. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strtok (char* s1, const char* s2);/ -<tag/Description/<tt/strtok/ will break the string s1 into a sequence of -tokens, which are delimited by characters from the string s2. The first call -to <tt/strtok/ will return a pointer to the first token in the string s1. -Following calls must pass a <tt/NULL/ pointer as s1 in order to get the next -token in the string. Different sets of delimiters may be used for the -subsequent calls to <tt/strtok/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item><tt/strtok/ will modify the string s1. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcspn" name="strcspn">, -<!-- <ref id="strpbrk" name="strpbrk"> --> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strxfrm<label id="strxfrm"><p> - -<quote> -<descrip> -<tag/Function/Transform a string. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/size_t __fastcall__ strxfrm (char* s1, const char* s2, size_t n);/ -<tag/Description/The <tt/strxfrm/ function transforms the string pointed to by -s2 and places the resulting string into the string pointed to by s1. The -transformation is such that if the <tt/strcmp/ function is applied to two -transformed strings, it returns a value greater than, equal to, or less than -zero, corresponding to the result of the <tt/strcoll/ function applied to the -same two original strings. No more than n characters are placed into the -resulting array pointed to by s1, including the terminating null character. -<tag/Limits/<itemize> -<item><tt/s1/ and <tt/s2/ must not point to the same memory area, otherwise -the behaviour is undefined. -<item>If <tt/n/ is zero, <tt/s1/ may be a NULL pointer. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>Since cc65 doesn't support different charcter sets, <tt/strxfrm/ will -just copy s2 to s1 using <tt><ref id="strncpy" name="strncpy"></tt>. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="strcmp" name="strcmp">, -<ref id="strcoll" name="strcoll">, -<ref id="strncpy" name="strncpy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strupper<label id="strupper"><p> - -<quote> -<descrip> -<tag/Function/Make a string upper case. -<tag/Header/<tt/<ref id="string.h" name="string.h">/ -<tag/Declaration/<tt/char* __fastcall__ strupper (char* s);/ -<tag/Description/The <tt/strupper/ function will apply the <tt/toupper/ -function to each character of a string. The function will always return <tt/s/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The function prototype is unavailable when compiling in strict ANSI mode. -<item>An alias name for this function is <tt/strupr/. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="strlower" name="strlower"> -<ref id="toupper" name="toupper"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>strupr<label id="strupr"><p> - -<quote> -See <tt/strupper/. -</quote> - - -<sect1>telldir<label id="telldir"><p> - -<quote> -<descrip> -<tag/Function/Return the current position of a directory stream. -<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ -<tag/Declaration/<tt/long __fastcall__ telldir (DIR* dir);/ -<tag/Description/<tt/telldir/ returns the current position of a directory -stream. The return value may be used in subsequent calls to -<tt/<ref id="seekdir" name="seekdir">/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="seekdir" name="seekdir">, -<ref id="telldir" name="telldir"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>textcolor<label id="textcolor"><p> - -<quote> -<descrip> -<tag/Function/Set the text color. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ textcolor (unsigned char color);/ -<tag/Description/The function will set a new text color. It returns the old -(current) text color. Text output using any <tt/conio.h/ function will use -the color set by this function. -<tag/Limits/<itemize> -<item>Text colors are system dependent. The function may have no effect -on systems where the text color cannot be changed. -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="bgcolor" name="bgcolor">, -<ref id="bordercolor" name="bordercolor"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_arc<label id="tgi_arc"><p> - -<quote> -<descrip> -<tag/Function/Draw an elliptic arc in the current color. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_arc (int x, int y, -unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);/ -<tag/Description/The function draws an elliptic arc with center at x/y and -radii rx/ry using the current drawing color. The arc covers the angle -between sa and ea (startangle and endangle), which must be in the range -0..360. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The function behaves unexpectedly or may crash if the angles are out -of range. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_bar" name="tgi_bar">, -<ref id="tgi_circle" name="tgi_circle">, -<ref id="tgi_ellipse" name="tgi_ellipse">, -<ref id="tgi_pieslice" name="tgi_pieslice">, -<ref id="tgi_setcolor" name="tgi_setcolor"> -<tag/Example/<verb> -/* Draw the upper half of an ellipse */ -tgi_setcolor(TGI_COLOR_BLUE); -tgi_arc (50, 50, 40, 20, 0, 180); -</verb> -</descrip> -</quote> - - -<sect1>tgi_bar<label id="tgi_bar"><p> - -<quote> -<descrip> -<tag/Function/The function fills a rectangle on the drawpage with the current -color. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_bar (int x1, int y1, int x2, int y2);/ -<tag/Description/The function fills a rectangle on the drawpage with the current -color. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi function -<tag/Example/<verb> -tgi_setcolor(TGI_COLOR_GREEN); -tgi_bar(10, 10, 100, 60); -</verb> -</descrip> -</quote> - - -<sect1>tgi_circle<label id="tgi_circle"><p> - -<quote> -<descrip> -<tag/Function/The function draws a circle in the current color. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_circle (int x, int y, unsigned char radius);/ -<tag/Description/The function draws a circle in the current color. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_arc" name="tgi_arc">, -<ref id="tgi_bar" name="tgi_bar">, -<ref id="tgi_ellipse" name="tgi_ellipse">, -<ref id="tgi_pieslice" name="tgi_pieslice">, -<ref id="tgi_setcolor" name="tgi_setcolor"> -<tag/Example/<verb> -tgi_setcolor(TGI_COLOR_BLACK); -tgi_circle(50, 40, 40); -</verb> -</descrip> -</quote> - - -<sect1>tgi_clear<label id="tgi_clear"><p> - -<quote> -<descrip> -<tag/Function/Clear the drawpage -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void tgi_clear (void);/ -<tag/Description/Clear the drawpage -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_done<label id="tgi_done"><p> - -<quote> -<descrip> -<tag/Function/End graphics mode, switch back to text mode. -Will NOT uninstall or unload the driver! -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void tgi_done (void);/ -<tag/Description/End graphics mode, switch back to text mode. -Will NOT uninstall or unload the driver! -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_ellipse<label id="tgi_ellipse"><p> - -<quote> -<descrip> -<tag/Function/The function draws an ellipse in the current color. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_ellipse (int x, int y, unsigned char rx, unsigned char ry);/ -<tag/Description/The function draws an ellipse at position x/y with radii -rx and ry, using the current drawing color. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_arc" name="tgi_arc">, -<ref id="tgi_bar" name="tgi_bar">, -<ref id="tgi_circle" name="tgi_circle">, -<ref id="tgi_pieslice" name="tgi_pieslice">, -<ref id="tgi_setcolor" name="tgi_setcolor"> -<tag/Example/<verb> -tgi_setcolor(TGI_COLOR_RED); -tgi_ellipse (50, 40, 40, 20); -</verb> -</descrip> -</quote> - - -<sect1>tgi_free_vectorfont<label id="tgi_free_vectorfont"><p> - -<quote> -<descrip> -<tag/Function/Free a vector font that was previously loaded into memory. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_free_vectorfont (const tgi_vectorfont* font);/ -<tag/Description/Free a vector font that was previously loaded into memory. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_load_vectorfont" name="tgi_load_vectorfont">, -<ref id="tgi_install_vectorfont" name="tgi_install_vectorfont"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getaspectratio<label id="tgi_getaspectratio"><p> - -<quote> <descrip> <tag/Function/Return the pixel aspect ratio. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned tgi_getaspectratio (void);/ -<tag/Description/The function returns the pixel aspect ratio for the current -driver and display as an 8.8 fixed point value. It may be used to correct -geometric shapes so they look correct on the display. As an example, a circle -with a radius of 100 pixels may look elliptic on some driver/display -combinations if the aspect ratio is not 1.00. -<tag/Limits/<itemize> -<item>The aspect ratio is encoded in the TGI driver which assumes a "standard" -monitor for the given platform. The aspect ratio may be wrong if another -monitor is used. -<item>No TGI function will use the aspect ratio. It is up to the programmer to -make use of it. -<item>The <ref id="tgi_setaspectratio" name="tgi_setaspectratio"> function can -be used to change the aspect ratio for a loaded driver. The value is not reset -by <ref id="tgi_init" name="tgi_init">, so if a driver is linked statically to -an application, switching into and out of graphics mode will not restore the -original aspect ratio. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_setaspectratio" name="tgi_setaspectratio"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getcolor<label id="tgi_getcolor"><p> - -<quote> -<descrip> -<tag/Function/Return the current drawing color. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned char tgi_getcolor (void);/ -<tag/Description/The actual color is an index to a palette. During tgi_init -you will get a default palette. The number of colors depend on the platform. -All platforms recognize at least TGI_COLOR_BLACK and TGI_COLOR_WHITE. But some -platforms have many more predefined colors. If you paint using TGI_COLOR_GREEN -and then you change the green of the palette to blue using tgi_setpalette then -after this painting in TGI_COLOR_GREEN will actually be blue. -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/<verb> -color = tgi_getcolor(); -</verb> -</descrip> -</quote> - - -<sect1>tgi_getcolorcount<label id="tgi_getcolorcount"><p> - -<quote> -<descrip> -<tag/Function/Get the number of available colors. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned char tgi_getcolorcount (void);/ -<tag/Description/Tgi platforms use indexed color palettes. This function -returns the number of entries we can use in the palette. -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/<verb> -if (tgi_getcolorcount() == 2) { - printf("Only monochrome graphics is supported\n"); -} -</verb> -</descrip> -</quote> - - -<sect1>tgi_getdefpalette<label id="tgi_getdefpalette"><p> - -<quote> -<descrip> -<tag/Function/Get the palette installed by default. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/const unsigned char* tgi_getdefpalette (void);/ -<tag/Description/The tgi driver has a default palette that is active at startup. -The named colors TGI_COLOR_BLACK, TGI_COLOR_WHITE, TGI_COLOR_RED... need this -palette to work correctly. -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_geterror<label id="tgi_geterror"><p> - -<quote> -<descrip> -<tag/Function/Return the error code for the last operation. -This will also clear the error. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned char tgi_geterror (void);/ -<tag/Description/Return the error code for the last operation. -This will also clear the error. -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_geterrormsg<label id="tgi_geterrormsg"><p> - -<quote> -<descrip> -<tag/Function/Get an error message describing the error. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/const char* __fastcall__ tgi_geterrormsg (unsigned char code);/ -<tag/Description/Get an error message describing the error. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getmaxcolor<label id="tgi_getmaxcolor"><p> - -<quote> -<descrip> -<tag/Function/Get the highest index of the palette. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned char tgi_getmaxcolor (void);/ -<tag/Description/Get the highest index of the palette. -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getmaxx<label id="tgi_getmaxx"><p> - -<quote> -<descrip> -<tag/Function/Get the maximum x coordinate that can be used on this screen. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned tgi_getmaxx (void);/ -<tag/Description/Get the maximum x coordinate that can be used on this screen. -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getmaxy<label id="tgi_getmaxy"><p> - -<quote> -<descrip> -<tag/Function/Get the maximum y coordinate that can be used on this screen. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned tgi_getmaxy (void);/ -<tag/Description/Get the maximum y coordinate that can be used on this screen. -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getpagecount<label id="tgi_getpagecount"><p> - -<quote> -<descrip> -<tag/Function/Return the number of screen pages available. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned tgi_getpagecount (void);/ -<tag/Description/Return the number of screen pages available. -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_setdrawpage" name="tgi_setdrawpage">, -<ref id="tgi_setviewpage" name="tgi_setviewpage"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getpalette<label id="tgi_getpalette"><p> - -<quote> -<descrip> -<tag/Function/Get the palette installed. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/const unsigned char* tgi_getpalette (void);/ -<tag/Description/Get the palette installed. -<tag/Availability/cc65 -<tag/See also/Other tgi functions -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getpixel<label id="tgi_getpixel"><p> - -<quote> -<descrip> -<tag/Function/Get the color of a pixel from the viewpage. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ tgi_getpixel (int x, int y);/ -<tag/Description/Get the color of a pixel from the viewpage. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getxres<label id="tgi_getxres"><p> - -<quote> -<descrip> -<tag/Function/Get number of horisontal pixels on the screen. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned tgi_getxres (void);/ -<tag/Description/Get number of horisontal pixels on the screen. -This is same as tgi_maxx()+1. -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_getyres<label id="tgi_getyres"><p> - -<quote> -<descrip> -<tag/Function/Get number of vertical pixels on the screen. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned tgi_getyres (void);/ -<tag/Description/Get number of vertical pixels on the screen. -This is same as tgi_maxy()+1. -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_gotoxy<label id="tgi_gotoxy"><p> - -<quote> -<descrip> -<tag/Function/Set graphics cursor at x, y. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_gotoxy (int x, int y);/ -<tag/Description/Set graphics cursor at x, y. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_init<label id="tgi_init"><p> - -<quote> -<descrip> -<tag/Function/Initialize the already loaded graphics driver. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void tgi_init (void);/ -<tag/Description/The tgi_init function will set the default palette to the -hardware. -<tag/Limits/<itemize> -<item><tt/tgi_init/ will not clear the screen. This allows switching between -text and graphics mode on platforms that have separate memory areas for the -screens. If you want the screen cleared, call <tt/<ref id="tgi_clear" -name="tgi_clear">/ after <tt/tgi_init/. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/<verb> -tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it. -tgi_init(); //Set up the default palette and clear the screen. -</verb> -</descrip> -</quote> - - -<sect1>tgi_install<label id="tgi_install"><p> - -<quote> -<descrip> -<tag/Function/Install an already loaded driver and return an error code. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned char __fastcall__ tgi_install (void* driver);/ -<tag/Description/The function installs a driver that was already loaded into -memory (or linked statically to the program). It returns an error code -(<tt/TGI_ERR_OK/ in case of success). -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_load_driver" name="tgi_load_driver">, -<ref id="tgi_uninstall" name="tgi_uninstall">, -<ref id="tgi_unload" name="tgi_unload"> -<tag/Example/<verb> -tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it. -tgi_init(); //Set up the default palette and clear the screen. -</verb> -</descrip> -</quote> - - -<sect1>tgi_install_vectorfont<label id="tgi_install_vectorfont"><p> - -<quote> -<descrip> -<tag/Function/Install an already loaded driver and return an error code. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_install_vectorfont (const tgi_vectorfont* font);/ -<tag/Description/ -Install a vector font for use. More than one vector font can be loaded, -but only one can be active. This function is used to tell which one. Call -with a NULL pointer to uninstall the currently installed font. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_load_vectorfont" name="tgi_load_vectorfont">, -<ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_ioctl<label id="tgi_ioctl"><p> - -<quote> -<descrip> -<tag/Function/Platform dependent code extensions. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned __fastcall__ tgi_ioctl (unsigned char code, void* data);/ -<tag/Description/Some platforms have extra display hardware that is not -supported by standard tgi functions. You can extend the driver to support -this extra hardware using tgi_ioctl functions. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>These functions are not easily portable to other cc65 platforms. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/<verb> -#define tgi_sprite(spr) tgi_ioctl(0, (void*)(spr)) -#define tgi_flip() tgi_ioctl(1, (void*)0) -#define tgi_setbgcolor(bgcol) tgi_ioctl(2, (void*)(bgcol)) -#define tgi_setframerate(rate) tgi_ioctl(3, (void*)(rate)) -#define tgi_busy() tgi_ioctl(4, (void*)0) -#define tgi_updatedisplay() tgi_ioctl(4, (void*)1) -if (!tgi_busy()) { - tgi_sprite(&background); - tgi_setcolor(TGI_COLOR_BLUE); - tgi_outttextxy(20,40,"Hello World"); - tgi_updatedisplay(); -} -</verb> -</descrip> -</quote> - - -<sect1>tgi_line<label id="tgi_line"><p> - -<quote> -<descrip> -<tag/Function/Draw a line in the current drawing color. -The graphics cursor will be set to x2/y2 by this call. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_line (int x1, int y1, int x2, int y2);/ -<tag/Description/Draw a line in the current drawing color. -The graphics cursor will be set to x2/y2 by this call. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_lineto<label id="tgi_lineto"><p> - -<quote> -<descrip> -<tag/Function/Draw a line in the current drawing color from the graphics -cursor to the new end point. The graphics cursor will be updated to x2/y2. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_lineto (int x2, int y2);/ -<tag/Description/Draw a line in the current drawing color from the graphics -cursor to the new end point. The graphics cursor will be updated to x2/y2. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_load_driver<label id="tgi_load_driver"><p> - -<quote> -<descrip> -<tag/Function/Load and install the given driver. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_load_driver (const char *name);/ -<tag/Description/Load and install the driver by name. -Will just load the driver and check if loading was successful. -Will not switch to graphics mode. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_load_vectorfont<label id="tgi_load_vectorfont"><p> - -<quote> -<descrip> -<tag/Function/Load the given vector font. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/const tgi_vectorfont* __fastcall__ tgi_load_vectorfont (const char* name);/ -<tag/Description/ -Load a vector font into memory and return it. In case of errors, NULL is -returned and an error is set, which can be retrieved using tgi_geterror. -To use the font, it has to be installed using tgi_install_vectorfont. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_install_vectorfont" name="tgi_install_vectorfont">, -<ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_outtext<label id="tgi_outtext"><p> - -<quote> -<descrip> -<tag/Function/Output text at the current graphics cursor position. -The graphics cursor is moved to the end of the text. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_outtext (const char* s);/ -<tag/Description/Output text at the current graphics cursor position. -The graphics cursor is moved to the end of the text. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_outtextxy<label id="tgi_outtextxy"><p> - -<quote> -<descrip> -<tag/Function/Output text at the given cursor position. -The graphics cursor is moved to the end of the text. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_outtextxy (int x, int y, const char* s);/ -<tag/Description/Output text at the given cursor position. -The graphics cursor is moved to the end of the text. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_pieslice<label id="tgi_pieslice"><p> - -<quote> -<descrip> -<tag/Function/Draw an elliptic pie slice in the current color. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_pie slice (int x, int y, -unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);/ -<tag/Description/The function draws an elliptic pie slice with center at x/y -and radii rx/ry using the current drawing color. The pie slice covers the angle -between sa and ea (startangle and endangle), which must be in the range -0..360. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>The function behaves unexpectedly or may crash if the angles are out -of range. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_bar" name="tgi_arc">, -<ref id="tgi_bar" name="tgi_bar">, -<ref id="tgi_circle" name="tgi_circle">, -<ref id="tgi_ellipse" name="tgi_ellipse">, -<ref id="tgi_setcolor" name="tgi_setcolor"> -<tag/Example/<verb> -/* Draw the closed upper half of an ellipse */ -tgi_setcolor(TGI_COLOR_BLUE); -tgi_pieslice (50, 50, 40, 20, 0, 180); -</verb> -</descrip> -</quote> - - -<sect1>tgi_setaspectratio<label id="tgi_setaspectratio"><p> - -<quote> <descrip> <tag/Function/Set the pixel aspect ratio. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_setaspectratio (unsigned ratio);/ -<tag/Description/The function sets the pixel aspect ratio for the current -driver and display. The argument is an 8.8 fixed point value. The aspect ratio -may be used to correct geometric shapes so they look correct on a given -display. As an example, a circle with a radius of 100 pixels may look elliptic -on some driver/display combinations if the aspect ratio is not 1.00. -<tag/Limits/<itemize> -<item>The aspect ratio is encoded in the TGI driver which assumes a "standard" -monitor for the given platform. The aspect ratio may be wrong if another -monitor is used. -<item>No TGI function will use the aspect ratio. It is up to the programmer to -make use of it. -<item>The <tt/tgi_setaspectratio/ function can be used to change the aspect -ratio for a loaded driver. The value is not reset by <ref id="tgi_init" -name="tgi_init">, so if a driver is linked statically to an application, -switching into and out of graphics mode will not restore the original aspect -ratio. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_getaspectratio" name="tgi_getaspectratio"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tgi_setcolor<label id="tgi_setcolor"><p> - -<quote> -<descrip> -<tag/Function/Set color to be used in future draw operations. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_setcolor (unsigned char color);/ -<tag/Description/Set color to be used in future draw operations. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/<verb> -tgi_setcolor(TGI_COLOR_BLACK); -tgi_bar(0,0,30,30); -tgi_setcolor(TGI_COLOR_WHITE); -tgi_bar(10,10,20,20); -</verb> -</descrip> -</quote> - -<sect1>tgi_setdrawpage<label id="tgi_setdrawpage"><p> - -<quote> -<descrip> -<tag/Function/Set the page for drawing. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_setdrawpage (unsigned char page);/ -<tag/Description/If the drawpage and the viewpage are the same then all drawing -is seen immediately as it is drawn. For double buffered games you can set the -drawpage to a different page than the viewpage. This lets you draw the next -screen in the background and when the screen is ready you display it. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/<verb> -tgi_setdrawpage(1); -tgi_outtextxy(10, 10, "Hello World"); -tgi_setviewpage(1); // Show page 1 -tgi_setdrawpage(0); -tgi_outtextxy(10, 10, "Creating next frame"); -... -tgi_setviewpage(0); // Show page 0 -</verb> -</descrip> -</quote> - -<sect1>tgi_setpalette<label id="tgi_setpalette"><p> - -<quote> -<descrip> -<tag/Function/Set the palette (not available with all drivers/hardware). -Palette is a pointer to as many entries as there are colors. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_setpalette (const unsigned char* palette);/ -<tag/Description/Set the palette (not available with all drivers/hardware). -Palette is a pointer to as many entries as there are colors. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - -<sect1>tgi_setpixel<label id="tgi_setpixel"><p> - -<quote> -<descrip> -<tag/Function/Plot a pixel on the drawpage with the current color. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_setpixel (int x, int y);/ -<tag/Description/Plot a pixel on the drawpage with the current color. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - -<sect1>tgi_setviewpage<label id="tgi_setviewpage"><p> - -<quote> -<descrip> -<tag/Function/Set page to be visible on screen. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_setviewpage (unsigned char page);/ -<tag/Description/If the drawpage and the viewpage are the same then all drawing -is seen immediately as it is drawn. For double buffered games you can set the -drawpage to a different page than the viewpage. This lets you draw the next -screen in the background and when the screen is ready you display it. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/<verb> -tgi_setdrawpage(1); -tgi_outtextxy(10, 10, "Hello World"); -tgi_setviewpage(1); // Show page 1 -tgi_setdrawpage(0); -tgi_outtextxy(10, 10, "Creating next frame"); -... -tgi_setviewpage(0); // Show page 0 -</verb> -</descrip> -</quote> - -<sect1>tgi_gettextheight<label id="tgi_gettextheight"><p> - -<quote> -<descrip> -<tag/Function/Calculate the height of the text in pixels according to -the current text style. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned __fastcall__ tgi_gettextheight (const char* s);/ -<tag/Description/Calculate the height of the text in pixels according to -the current text style. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - -<sect1>tgi_settextscale<label id="tgi_settextscale"><p> - -<quote> -<descrip> -<tag/Function/Set the scaling for text output. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_settextscale (unsigned width, unsigned height);/ -<tag/Description/ -Set the scaling for text output. The scaling factors for width and height -are 8.8 fixed point values. This means that $100 = 1 $200 = 2 etc. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_settextstyle" name="tgi_settextstyle"> -<tag/Example/None. -</descrip> -</quote> - -<sect1>tgi_settextstyle<label id="tgi_settextstyle"><p> - -<quote> -<descrip> -<tag/Function/Set the style for text output. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void __fastcall__ tgi_settextstyle (unsigned char magx, unsigned char magy, unsigned char dir, unsigned char font);/ -<tag/Description/Set the style for text output. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="tgi_settextscale" name="tgi_settextscale"> -<tag/Example/None. -</descrip> -</quote> - -<sect1>tgi_gettextwidth<label id="tgi_gettextwidth"><p> - -<quote> -<descrip> -<tag/Function/Calculate the width of the text in pixels according to the current text style. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/unsigned __fastcall__ tgi_gettextwidth (const char* s);/ -<tag/Description/Calculate the width of the text in pixels according to the current text style. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - -<sect1>tgi_uninstall<label id="tgi_uninstall"><p> - -<quote> -<descrip> -<tag/Function/Uninstall the currently loaded driver but do not unload it. -Will call tgi_done if necessary. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void tgi_uninstall (void);/ -<tag/Description/Uninstall the currently loaded driver but do not unload it. -Will call tgi_done if necessary. -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - -<sect1>tgi_unload<label id="tgi_unload"><p> - -<quote> -<descrip> -<tag/Function/Uninstall, then unload the currently loaded driver. -Will call tgi_done if necessary. -<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ -<tag/Declaration/<tt/void tgi_unload (void);/ -<tag/Description/Uninstall, then unload the currently loaded driver. -Will call tgi_done if necessary. -<tag/Availability/cc65 -<tag/See also/Other tgi functions. -<tag/Example/None. -</descrip> -</quote> - -<sect1>time<label id="time"><p> - -<quote> -<descrip> -<tag/Function/Get the time. -<tag/Header/<tt/<ref id="time.h" name="time.h">/ -<tag/Declaration/<tt/time_t __fastcall__ time (time_t* t);/ -<tag/Description/The function returns the time since the 1970-01-01 00:00:00 -measured in seconds. If the pointer <tt/t/ is not <tt/NULL/, the function -result will also be stored there. If no time is available, <tt/(time_t)-1/ is -returned and <tt/errno/ is set to <tt/ENOSYS/. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -<item>Many platforms supported by cc65 do not have a realtime clock, so the -returned value may not be valid. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="clock" name="clock"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>toggle_videomode<label id="toggle_videomode"><p> - -<quote> -<descrip> -<tag/Function/Toggle between 40 and 80 column mode. -<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ -<tag/Declaration/<tt/void toggle_videomode (void);/ -<tag/Description/Toggle between 40 and 80 column mode. The settings for the -old mode (cursor position, color and so on) are saved and restored together -with the mode. -<tag/Limits/<itemize> -<item>The function is specific to the C128. -<item>This function is deprecated. Please use <ref id="videomode" -name="videomode"> instead! -</itemize> -<tag/Availability/C128 -<tag/See also/ -<ref id="fast" name="fast">, -<ref id="slow" name="slow">, -<ref id="videomode" name="videomode"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>tolower<label id="tolower"><p> - -<quote> -<descrip> -<tag/Function/Convert a character into its lower case representation. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ tolower (int c);/ -<tag/Description/The function returns the given character converted to lower -case. If the given character is not a letter, it is returned unchanged. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="islower" name="islower">, -<ref id="isupper" name="isupper">, -<ref id="toupper" name="toupper"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>toupper<label id="toupper"><p> - -<quote> -<descrip> -<tag/Function/Convert a character into its upper case representation. -<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ -<tag/Declaration/<tt/int __fastcall__ toupper (int c);/ -<tag/Description/The function returns the given character converted to upper -case. If the given character is not a letter, it is returned unchanged. -<tag/Limits/<itemize> -<item>The function is only available as fastcall function, so it may -only be used in presence of a prototype. -</itemize> -<tag/Availability/ISO 9899 -<tag/See also/ -<ref id="islower" name="islower">, -<ref id="isupper" name="isupper">, -<ref id="tolower" name="tolower"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>ultoa<label id="ultoa"><p> - -<quote> -<descrip> -<tag/Function/Convert an unsigned long integer into a string. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/char* __fastcall__ ultoa (unsigned long val, char* buf, int radix);/ -<tag/Description/<tt/itoa/ converts the unsigned long integer <tt/val/ into a -string using <tt/radix/ as the base. -<tag/Limits/<itemize> -<item>There are no provisions to prevent a buffer overflow. -<item>The function is non standard, so it is not available in strict ANSI mode. -You should probably use <tt/sprintf/ instead. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="atoi" name="atoi">, -<ref id="atol" name="atol">, -<ref id="itoa" name="itoa">, -<ref id="ltoa" name="ltoa">, -<ref id="utoa" name="utoa"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>unlink<label id="unlink"><p> - -<quote> -<descrip> -<tag/Function/Delete a file. -<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ -<tag/Declaration/<tt/int __fastcall__ unlink (const char* name);/ -<tag/Description/<tt/unlink/ deletes the file with the given name. On success, -zero is returned. On error, -1 is returned and <tt/errno/ is set to an error -code describing the reason for the failure. -<tag/Limits/ -<itemize> -<item>The use of this function is discouraged. Please use <tt/<ref id="remove" -name="remove">/ instead, which is a native ANSI C function and does the same. -<item>This function is not available on all cc65 targets (depends on the -availability of file I/O). -<item>The function is only available as fastcall function, so it may only -be used in presence of a prototype. -<item>Instead of <tt/unlink/, <tt/<ref id="remove" name="remove">/ should be -used, which has the same semantics, but is more portable, because it conforms -to the ISO C standard. -</itemize> -<tag/Availability/POSIX 1003.1 -<tag/See also/ -<ref id="remove" name="remove"> -<tag/Example/ -<verb> -#include <stdio.h> -#include <unistd.h> - -#define FILENAME "helloworld" - -if (unlink (FILENAME) == 0) { - printf ("We deleted %s successfully\n", FILENAME); -} else { - printf ("There was a problem deleting %s\n", FILENAME); -} -</verb> -</descrip> -</quote> - - -<sect1>utoa<label id="utoa"><p> - -<quote> -<descrip> -<tag/Function/Convert an unsigned integer into a string. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/char* __fastcall__ utoa (unsigned val, char* buf, int radix);/ -<tag/Description/<tt/itoa/ converts the unsigned integer <tt/val/ into a string -using <tt/radix/ as the base. -<tag/Limits/<itemize> -<item>There are no provisions to prevent a buffer overflow. -<item>The function is non standard, so it is not available in strict ANSI mode. -You should probably use <tt/sprintf/ instead. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="atoi" name="atoi">, -<ref id="atol" name="atol">, -<ref id="itoa" name="itoa">, -<ref id="ltoa" name="ltoa">, -<ref id="ultoa" name="ultoa"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>vcprintf<label id="vcprintf"><p> - -<quote> -<descrip> -<tag/Function/Formatted output to the console. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/int __fastcall__ vcprintf (const char* format, va_list ap);/ -<tag/Description/The arguments specified as a <tt/va_list/ are converted to -text where necessary and formatted according to the format string given. The -resulting string is output to the console. <tt/vcprintf/ supports the same -format specifiers as <tt/vprintf/. <!-- <tt/<ref id="vprintf" name="vprintf">/. --> -<tag/Limits/<itemize> -<item>Like all other <tt/conio/ output functions, <tt/vcprintf/ distinguishes -between <tt/\r/ and <tt/\n/. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/cc65 -<tag/See also/ -<ref id="cprintf" name="cprintf">, -<ref id="cputc" name="cputc">, -<ref id="cputcxy" name="cputcxy">, -<ref id="cputs" name="cputs">, -<ref id="cputsxy" name="cputsxy"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>videomode<label id="videomode"><p> - -<quote> -<descrip> -<tag/Function/Switch to either 40 or 80 column mode. -<tag/Header/<tt/<ref id="apple2enh.h" name="apple2enh.h">, -<ref id="c128.h" name="c128.h">/ -<tag/Declaration/<tt/unsigned __fastcall__ videomode (unsigned Mode);/ -<tag/Description/Switch to 40 or 80 column mode depending on the argument. If -the requested mode is already active, nothing happens. The old mode is returned -from the call. -<tag/Limits/<itemize> -<item>The function is specific to the C128 and enhanced Apple //e. -<item>This function replaces <ref id="toggle_videomode" -name="toggle_videomode">. -<item>The function is only available as fastcall function, so it may only be -used in presence of a prototype. -</itemize> -<tag/Availability/C128 and enhanced Apple //e -<tag/See also/ -<ref id="fast" name="fast">, -<ref id="slow" name="slow">, -<ref id="toggle_videomode" name="toggle_videomode"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>wherex<label id="wherex"><p> - -<quote> -<descrip> -<tag/Function/Return the current X position of the text mode cursor. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/unsigned char wherex (void);/ -<tag/Description/The function returns the current X position of the text mode -cursor. Zero is returned for the leftmost screen position. -<tag/Availability/cc65 -<tag/See also/ -<ref id="gotox" name="gotox">, -<ref id="gotoy" name="gotoy">, -<ref id="gotoxy" name="gotoxy">, -<ref id="wherey" name="wherey"> -<tag/Example/None. -</descrip> -</quote> - - -<sect1>wherey<label id="wherey"><p> - -<quote> -<descrip> -<tag/Function/Return the current Y position of the text mode cursor. -<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ -<tag/Declaration/<tt/unsigned char wherey (void);/ -<tag/Description/The function returns the current Y position of the text mode -cursor. Zero is returned for the uppermost screen position. -<tag/Availability/cc65 -<tag/See also/ -<ref id="gotox" name="gotox">, -<ref id="gotoy" name="gotoy">, -<ref id="gotoxy" name="gotoxy">, -<ref id="wherex" name="wherex"> -<tag/Example/None. -</descrip> -</quote> - - -</article> diff --git a/doc/geos.sgml b/doc/geos.sgml deleted file mode 100644 index 8a5a948a1..000000000 --- a/doc/geos.sgml +++ /dev/null @@ -1,1662 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<!-- Title information --> - -<title>GEOSLib docs -<author>Maciej Witkowiak, <htmlurl url="mailto:ytm@elysium.pl" name="ytm@elysium.pl"> -<date>v1.5, 26.12.1999, 2000, 2001, 2002, 2003, 2005 -<abstract> -This is the documentation of cc65's GEOSLib, but information contained here may be also -useful for writing GEOS applications in general. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Introduction -<p> -As we all know that the best computers in the world are the C64 and C128. They have their GUI too - -the excellent GEOS. GEOS seems very difficult and cryptic for many people, from programmer's point -of view. That's not true. The designers of GEOS created a flexible and powerful system, which -is easy to use and program. -<p> -Coding GEOS in C? That's something new. It is possible now - with Ulrich von Bassewitz's cc65 -package and my GEOSLib you are able to create GEOS applications in no time. -<p> -GEOSLib supports a subset of the standard cc65 libraries. Whenever possible native Kernal functions -are used (e.g. <tt/memset/ is an alias for <tt/FillRam/), however not all are supported. E.g. -string functions like <tt/strcmp/, <tt/strcpy/ are doubled with native <tt/CmpString/, -<tt/CopyString/ because the latter can handle only 256 byte strings. Keep this in mind when -you write your program. If you don't need long strings simply use functions from the Kernal, -the resulting code will be smaller. -<p> -<tt/dio/ - direct disk access is available, but you might have problems with devices other -than 1541, 1571 or 1581. RAM drives emulating these should work. -<p> -<tt/conio/ - simple console input-output is available for command line applications. -This implementation assumes that one character does fit in 8x8 cell, so output with -default BSW font, which is has 9 points, might be a bit messy. There is no color support in -GEOS 2.0 so color functions are disabled. Both 40 and 80 column modes are supported -and automatically detected. -<p> -<tt/tgi/ - TGI driver for GEOS that supports both 40 and 80 column modes but mode can not be -changed between <tt/tgi_init/ and <tt/tgi_done/. -<p> -<tt/joy/ - JOY driver for GEOS that supports only joystick, not current pointing device. -<p> -It is safe to use these standard includes and their contents: -<tt/assert.h, conio.h, dio.h, errno.h, em.h, geos.h, joystick.h, modload.h, mouse.h, stdlib.h, string.h, tgi.h, time.h/ -<p> -For <tt/time.h/ functions <tt/systime()/ and <tt/clock()/ note that the resolution is one second. -<p> -Functions from the headers above are either standard C library functions or cc65-specific, in -either case they are not GEOS specific and so they are not described here. -<p> -I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best -available code (well, the best as for machine :-). Many of the <tt/void foo (void)/ functions are -just raw calls to the Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you -can find many definitions of standard GEOS locations. Access to these addresses is optimized by -cc65 to simple <tt/lda/ and <tt/sta/. Don't be afraid to use C syntax. - -<sect1>Requirements -<p> -You don't need a C64 or C128 for development. The only hardware requirement is a PC capable of -running cc65. You do however need C64 or C128 emulator and GEOS disk images (.d64) to test your -programs. - -The software needed: -<itemize> - <item><em/cc65/ Excellent package containing a C crosscompiler, a crossassembler and a linker, you - can get it from: <htmlurl url="http://www.cc65.org/" - name="http://www.cc65.org/"> - <item><em/VICE/ This is a portable C64, C128 and few other Commodore computers emulator, you - can obtain it from: <htmlurl url="http://www.viceteam.org/" - name="http://www.viceteam.org/">. The VICE package contains the - c1541 program that is able to convert/unconvert GEOS files to disk images. - <item><em/The Star Commander/ This tool is only for DOS. You will need it for transferring - object files from a PC to a 1541. There's also one important ability of this - tool - it automatically un-converts .cvt files into GEOS native format on - disk image files. Check out: <htmlurl url="http://sta.c64.org/sc.html" - name="http://sta.c64.org/sc.html"> - <item><em/cbm4linux/ A Linux kernel module that allows for communication with a 1541 and - other Commodore IEC bus drives. It can be a replacement for Star Commander if - you only want to transfer files to a disk and unconvert using GEOS program for - this purpose. Check out: <htmlurl url="http://www.lb.shuttle.de/puffin/cbm4linux/" - name="http://www.lb.shuttle.de/puffin/cbm4linux"> -</itemize> -<p> -VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only -needs cc65. -<p> -<em/Update:/ starting from v2.5.0 GEOSLib is a part of the cc65 package as its GEOS support library. - -<sect1>Legal -<p> -I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's -Reference Guide and BSW for GEOS. -<p> -GEOSLib is covered by the same license as cc65. You can find the whole text -among documentation. I would really appreciate if you would like to send me -your comments, suggestions, questions, changes, bug reports etc. I will also -appreciate if you will just give me a sign that you are using GEOSLib - not -especially something big and important, mail me even if you are just playing -with it. -<p> -You can send postcards with hellos to: -<p> -Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW -<p> -POLAND -<p> -e-mail: <tt/ytm@elysium.pl/ - -<sect>What do you have and what to do with it? -<p> -This chapter describes some rules you ought to obey, and how to use GEOSLib. - -<sect1>Usage -<p> -Apart from this file, which merely describes only standard GEOS library -functions, you should read the <tt/grc65/ (GEOS resource compiler) documentation. -There is information about necessary resource files (each GEOS application -needs at least one) and the build process - what should be done and in what -order. Please also read the cc65 documentation on how to compile C, assembler -and link everything together. -<p> -All in all, you just need to place -<tscreen><verb> -#include <geos.h> -</verb></tscreen> -at the top of your source. -<p> -As a general rule read the sources of the example programs and read the headers. -These are the most reliable sources of knowledge ;-). You will also find there -many C macros representing various arguments passed to the functions. Please use -them. You will find your sources easier to understand, and it will be easier -to find bugs. -<p> -All types used in GEOSLib are <tt/unsigned/. -<p> -Screen coordinates are given in pixels unless stated differently. - -<sect1>Notes on style -<p> -Contrary to a typical GEOS assembly program which has a main function called after loading that -setups the screen, menus, icons etc. exiting from the <tt/main/ function in C is equivalent to -calling <tt/exit()/. These two are the only safe methods of terminating applications. DO NOT -USE <tt/EnterDeskTop/! Your data may be lost as library destructors and functions registered -with <tt/atexit/ are not called. -<p> -For GEOS GUI applications the recommended program structure is to have everything initialized -in the <tt/main/ function and at the end of it a call to the <tt/MainLoop()/ function. WARNING! This -function never returns, any code between <tt/MainLoop();/ and the end of <tt/main/ will not -be executed. You have to call <tt/exit()/ explicitly somewhere in your code (e.g. in a menu -handler or via DialogBox action). -<p> -Whenever possible use definitions from <tt/gsym.h/. The resulting code is translated by cc65 into -series of <tt/lda/ and <tt/sta/, so you can't do it better :-). -<p> -Don't hesitate to use library functions. Everything was written with size and speed in mind. In -fact many calls are just redirections to the GEOS Kernal which results in a simple <tt/jsr/. -<p> -The <tt/main/ function receives the standard <tt/argc/ and <tt/argv/ parameters. There are -always either 1 or 3 parameters. The DOS application name is always set as <tt/argv[0]/. -If present, <tt/argv[1]/ and <tt/argv[2]/ will be set to the data filename and data diskname (it only -works if the user double-clicks on a data file associated with your application). Note that it is up -to your application to determine which of the available (up to four) disk drives has the disk -with given diskname inside. If this fails your program should ask to insert the proper disk into -one of available drives. -<p> -You might wonder why I have chosen a sometimes weird order of arguments in functions. I just -wanted to avoid unnecessary pushing and popping of arguments from the stack because cc65 can pass a single -<tt/unsigned int/ through CPU registers. -<p> -Do not try to compile in strict ANSI mode. The library uses cc65 extensions which are not available in -ANSI. -<p> -It is possible to use dynamically loaded modules, three such modules are provided: -A GEOS TGI driver, a GEOS EMD driver (for VDC extended memory) and a GEOS JOY driver. -Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special -recommendations, read the cc65 documentation about modules and the demo programs source code. - -<sect>Library Functions -<p> -Functions here are sorted more or less in the way they appear in the header files. This way I am able -to keep functions covering similar tasks near each other. All function names are identical to those -from the <tt/geosSym/ file provided with the GeoProgrammer package. Only my extensions to <tt/geosSym/ -are covered by new names, but I tried to keep them in the naming convention. - -<sect1>Graphics -<p> -This section covers the drawing package of GEOS along with text output routines. - -<sect2>SetPattern -<p> -<tt/void SetPattern (char pattern)/ -<p> -This function sets the current pattern to the given. There are 32 different patterns in GEOS. You can -see them together in the filling box in GeoPaint. - -<sect2>GraphicsString -<p> -<tt/void GraphicsString (char *myGString)/ -<p> -One of the more powerfull routines of GEOS. This function calls other graphic functions depending -on the given command string. See the structures chapter for a more detailed description. - -<sect2>Rectangle functions -<p> -Parameters to those functions are grouped in the <tt/struct window drawWindow/. To speed up things and -reduce overhead this structure is bound to zero page locations, where all rectangle functions -expect their parameters. You can modify the data directly (e.g. <tt/drawWindow.top=10/) or via the -<tt/InitDrawWindow/ function. Contents of <tt/drawWindow/ are guaranteed not to change when only -using graphics functions. In other cases you should keep your data in separate <tt/struct window/ -and use <tt/InitDrawWindow/ before the first call to one of the rectangle functions. - -<sect3>InitDrawWindow -<p> -<tt/void InitDrawWindow (struct window *myWindow)/ -<p> -This function only copies the contents of <tt/myWindow/ into the system area of <tt/drawWindow/. Use it -if for some reason you have to keep your window data out of the zero page space. - -<sect3>Rectangle -<p> -<tt/void Rectangle (void)/ -<p> -This draws on screen a rectangle filled with the current pattern. - -<sect3>FrameRectangle -<p> -<tt/void FrameRectangle (char pattern)/ -<p> -This one draws a frame with the given bit pattern (not a pattern from the GEOS palette). - -<sect3>InvertRectangle -<p> -<tt/void InvertRectangle (void)/ -<p> -Just as the name says... - -<sect3>ImprintRectangle and RecoverRectangle -<p> -<tt/void ImprintRectangle (void)/ -<p> -<tt/void RecoverRectangle (void)/ -<p> -These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/) the -backbuffer of the screen. For example when drawing a new menu box GEOS first uses -<tt/ImprintRectangle/ to save the area under the box, and restores it by <tt/RecoverRectangle/ upon -destroying the menu. - -<sect2>Line Functions -<p> -The GEOS drawing package is optimized so there are different functions for drawing vertical and -horizontal lines. - -<sect3>HorizontalLine -<p> -<tt/void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)/ -<p> -This function draws a horizontal line using the given pattern. Note that <tt/pattern/ is not a pattern -number as set in <tt/SetPattern/ but a true bit pattern. - -<sect3>InvertLine -<p> -<tt/void InvertLine (char y, unsigned xStart, unsigned xEnd)/ -<p> -There is only a horizontal version. - -<sect3>RecoverLine -<p> -<tt/void RecoverLine (char y, unsigned xStart, unsigned xEnd)/ -<p> -This function recovers a single line. It is utilized by <tt/RecoverRectangle/. See its description -for more details. - -<sect3>VerticalLine -<p> -<tt/void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)/ -<p> -This function draws a vertical line using the given pattern. Note that <tt/pattern/ is not a pattern -number as set in <tt/SetPattern/ but a true bit pattern. - -<sect3>DrawLine -<p> -<tt/void DrawLine (char mode, struct window *myWindow)/ -<p> -The <tt/top/ parameters of <tt/struct window/ describe the starting point of the line, while -<tt/bottom/ ones are for the ending point. If <tt/mode/ is <tt/DRAW_DRAW/ then the current pattern from -<tt/SetPattern/ is used for drawing. If <tt/mode/ is <tt/DRAW_ERASE/ then the line is erased from the -screen. If <tt/mode/ is <tt/DRAW_COPY/ then the line is copied from/to back/frontbuffer, according to -the <tt/dispBufferOn/ setting. - -<sect2>Point Functions -<p> -The parameters to these two functions are passed by a pointer to an own <tt/struct pixel/ filled with -proper values. - -<sect3>DrawPoint -<p> -<tt/void DrawPoint (char mode, struct pixel *myPixel)/ -<p> -Depending on <tt/mode/ (see <tt/DrawLine/) draws/erases/copies a single point -on the screen. - -<sect3>TestPoint -<p> -<tt/char TestPoint (struct pixel *myPixel)/ -<p> -This function tests if the given pixel is set and returns <tt/true/ (non-zero) or <tt/false/ (zero). - -<sect2>Character and string output - -<sect3>PutChar -<p> -<tt/void PutChar (char character, char y, unsigned x)/ -<p> -This function outputs a single character using the current style and font to the screen. - -<sect3>PutString -<p> -<tt/void PutString (char *myString, char y, unsigned x)/ -<p> -Same as <tt/PutChar/ except the fact that you can output a whole <tt/NULL/-terminated string. -See <tt/ggraph.h/ for the list of tokens that you can also place in the string - like <tt/CBOLDON/ or -<tt/COUTLINEON/. - -<sect3>PutDecimal -<p> -<tt/void PutDecimal (char parameter, unsigned value, char y, unsigned x)/ -<p> -This function converts <tt/value/ to its decimal representation and outputs it to the screen. -The <tt/parameter/ is the field width in pixels (range 1-31) and the mode bits. Depending on them -the string can be filled with zeroes (the string is always 5 characters long) or not and left or right -justified to the given pixel. See <tt/ggraph.h/ for predefined values for <tt/parameter/. - -<sect2>Font Handling - -<sect3>GetCharWidth -<p> -<tt/char GetCharWidth (char character)/ -<p> -This function returns the real width (in pixels) of the given character with the current font. It can be used -for counting the length of a string on the screen, allowing for indentation or justification. - -<sect3>LoadCharSet -<p> -<tt/void LoadCharSet (struct fontdesc *myFont)/ -<p> -This function forces GEOS to use the given font. <tt/myFont/ should be casted from a -pointer to the start of the area where a record from a font file (VLIR structure) was loaded. - -<sect3>UseSystemFont -<p> -<tt/void UseSystemFont (void)/ -<p> -This function forces GEOS to use the built-in BSW font. - -<sect2>Bitmap handling -<p> -I'm not quite sure how these functions are working (except <tt/BitmapUp/) so you should -probably look into the library sources and compare it with your knowledge. Please let me know -if something is wrong or broken. - -<sect3>BitmapUp -<p> -<tt/void BitmapUp (struct iconpic *myPic)/ -<p> -This function unpacks the bitmap and places it on the screen - just as you set it in the -<tt/struct iconpic/ pointer which you pass. See <tt/gstruct.h/ for a description of this -structure. Note that you can only use packed GEOS bitmaps - a simple Photo Scrap is in this format. - -<sect3>BitmapClip -<p> -<tt/void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)/ -<p> -This function acts similar to <tt/BitmapUp/ but you can also define which parts of the bitmap are -to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap, -and the number of rows to skip from the top if it. - -<sect3>BitOtherClip -<p> -<tt/void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop, - struct iconpic *myPic)/ -<p> -Similar to the previous one with some extension. <tt/proc1/ is called before reading a byte (it -returns in .A the next value), and <tt/proc2/ is called every time the parser reads a byte which is -not a piece of a pattern (byte of code greater than 219). Both procedures should be written -separately in assembler and declared as <tt/__fastcall__/ returning char. - -<sect1>Menus and Icons -<p> -Here you will find information about functions related with menus and icons. - -<sect2>Menus -<p> -Menus are essential for a GUI. GEOS can handle only one menu at a time, but each menu can call -another one, which results in a submenu tree. There can be up to 8 menu levels, each one with up -to 32 items. -<p> -Menus are initialized with <tt/DoMenu/ and then the Kernal takes care of everything. Your code -(called from an event handler) should be a function without parameters, returning void. You should -use <tt/DoPreviousMenu/ or <tt/GotoFirstMenu/ at least once in its code to have the screen clean. - -<sect3>DoMenu -<p> -<tt/void DoMenu (struct menu *myMenu)/ -<p> -This function initializes the GEOS menu processor and exits. See <tt/DoMenu structure/ for more -information about it. Know that many GEOS applications just initialize the screen, menu and -exit to the main Kernal loop, this proves the power of <tt/DoMenu/. - -<sect3>ReDoMenu -<p> -<tt/void ReDoMenu (void)/ -<p> -This simply redraws the menu at the lowest level. It works like calling <tt/DoMenu/ again with -the same parameters. - -<sect3>RecoverMenu -<p> -<tt/void RecoverMenu (void)/ -<p> -This function erases the current menu from the screen. It doesn't change the menu level. - -<sect3>RecoverAllMenus -<p> -<tt/void RecoverAllMenus (void)/ -<p> -This calls <tt/RecoverMenu/ and erases all menus from the screen. Then the menu level is -set to 0 (topmost). - -<sect3>DoPreviousMenu -<p> -<tt/void DoPreviousMenu (void)/ -<p> -This functions causes the menu processor to go back one menu level. You should use it in menu -handler code to have the screen clean. - -<sect3>GotoFirstMenu -<p> -<tt/void GotoFirstMenu (void)/ -<p> -This one jumps back to the topmost menu. If there is only a menu and one submenu it works the -same as <tt/DoPreviousMenu/. - -<sect2>Icon Functions -<p> -Icons are working similar to menus except the fact that there is only one level. Icons are -defined as a screen area filled with a bitmap, but if you would setup icons and erase the -screen they would still be active and clicking in the place where formerly an icon was would cause -an effect. Similarly if you would setup icons and then turn them off with <tt/ClearMouseMode/ -the bitmap would still be on the screen but clicking on it would not cause any action. -There is only one, but powerful icon function. - -<sect3>DoIcons -<p> -<tt/void DoIcons (struct icontab *myIconTab)/ -<p> -This function initializes all icons that are present on the screen at once. For more information -look at the <tt/Icons/ chapter in this manual. - -<sect1>DialogBoxes -<p> -This chapter covers the most powerful GEOS user interface function - <tt/DoDlgBox/. - -<sect2>GEOS standard - -<sect3>DoDlgBox -<p> -<tt/char DoDlgBox (char *dialogString)/ -<p> -This function returns one byte. It can be the value of one of six standard icons (see <tt/gdlgbox.h/) -or whatever the closing routine passes. Register <tt/r0L/ also contains this value. -<p> -Read the structures chapter for the specs of the <tt/dialogString/. - -<sect3>RstrFrmDialogue -<p> -<tt/char RstrFrmDialogue/ -<p> -This function is called from within DoDlgBox event. It immediately closes the DialogBox and returns -the owner ID (or whatever caller has in the .A register). - -<sect2>GEOSLib extensions -<p> -To simplify the usage of DoDlgBox from C I wrote some helper functions - wrappers for DoDlgBox, -with predefined data. In one word - these are standard DialogBoxes you can see in almost every -GEOS application. - -<sect3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk -<p> -<tt/char DlgBoxYesNo (char *line1, char *line2)/ -<p> -<tt/char DlgBoxOkCancel (char *line1, char *line2)/ -<p> -<tt/void DlgBoxOk (char *line1, char *line2)/ -<p> -These function show two lines of text in a standard-sized DialogBox. You can read the code of the -pressed icon from the return value. E.g. for <tt/DlgBoxYesNo/ it can only be <tt/YES/ or <tt/NO/. -You can pass an empty string or NULL to get a blank line. - -<sect3>DlgBoxGetString -<p> -<tt/char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)/ -<p> -This function prompts the user to enter a string of at most <tt/strlen/ characters. It is returned -in <tt/string/. The two given lines of text are shown above the input line. Please remember -that there is also a <tt/CANCEL/ icon in the DialogBox and you should test if user confirmed his -input or gave up. The <tt/string/ is also shown so you can place a default input there or remember -to place <tt/NULL/ at start. - -<sect3>DlgBoxFileSelect -<p> -<tt/char DlgBoxFileSelect (char *class, char filetype, char *filename)/ -<p> -This routine is the standard file selector. It can return <tt/OPEN/, <tt/CANCEL/ or disk error -on reading the directory or opening the disk. -There is also a <tt/DISK/ icon shown, but it is handled internally. You pass as input parameters -<tt/filetype/ and a pointer to a string containing the first part of a file's class. If this string is -empty (<tt/NULL/ at the start), then all files with given filetype will be shown. -<p> -At present this file selector handles only first 16 files of given type and supports only one -(current) drive. - -<sect3>MessageBox -<p> -<tt/char MessageBox (char mode, const char *format, ...)/ -<p> -This function is a more general one. It works very much like <tt/printf/ in a -box. The only difference is the <tt/mode/ parameter which allows for placing -default icons (see <tt/gdlgbox.h/ for list of possible <tt/MB_/ values). -Any too wide text will be clipped to the size of the default window. If <tt/mode/ -is invalid or equal to <tt/MB_EMPTY/ then the window will be closed -after a click. Otherwise the user must choose an icon. -<p> -Note: Use it if you really need (or if you use it in many places) as -it adds quite amount of code to your program. -<p> -Note: the formatted text <em/cannot exceed/ 255 bytes in length, there is no check -for that. - -<sect1>Mouse, Sprites and Cursors -<p> -You will find here functions related to sprite and mouse drawing and handling. - -<sect2>Mouse related functions -<p> -These cover the mouse - as a general pointing device, but expect users to utilize as different devices -as a digital or analog joystick, a mouse, a lightpen or a koalapad (whatever it is). - -<sect3>StartMouseMode -<p> -<tt/void StartMouseMode (void)/ -<p> -This function initializes the mouse vectors - <tt/mouseVector/ and <tt/mouseFaultVec/, and then -calls <tt/MouseUp/. - -<sect3>ClearMouseMode -<p> -<tt/void ClearMouseMode (void)/ -<p> -This function disables all mouse activities - icons and menus stop to respond to mouse events, -but they are not cleared from the screen. - -<sect3>MouseUp and MouseOff -<p> -<tt/void MouseUp (void)/ -<p> -<tt/void MouseOff (void)/ -<p> -The first function turns the mouse pointer on. It appears on the next IRQ. The second one does -the opposite - it turns off the pointer, but its position is still updated by the input driver. - -<sect3>IsMseInRegion -<p> -<tt/char IsMseInRegion (struct window *myWindow)/ -<p> -This function tests if the mouse pointer is actually in the given range of the screen. See <tt/gsprite.h/ for -a description of the bits in the return values - they describe the position in detail. - -<sect2>Sprites -<p> -You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse -pointer and sprite 1 can be overwritten when using a text prompt. You don't have to worry about -40/80 column issues because GEOS128 has a pretty good sprite emulator for the VDC. - -<sect3>DrawSprite -<p> -<tt/void DrawSprite (char sprite, char *mySprite)/ -<p> -This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which -is copied to the system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Hardware sprite registers are -not initialized and the sprite is not yet visible. - -<sect3>PosSprite -<p> -<tt/void PosSprite (char sprite, struct pixel *myPixel)/ -<p> -This function positions the sprite on the screen. The given coordinates are screen ones - they are -converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your -sprite off the left or top to the screen. - -<sect3>EnablSprite and DisablSprite -<p> -<tt/void EnablSprite (char sprite)/ -<p> -<tt/void DisablSprite (char sprite)/ -<p> -These two functions are responsible for making the sprite visible or not. - -<sect2>Cursors and Console - -<sect3>InitTextPrompt -<p> -<tt/void InitTextPrompt (char height)/ -<p> -This function initializes sprite 1 for a text prompt with given <tt/height/. This parameter can be in -range 1-48. - -<sect3>PromptOn and PromptOff -<p> -<tt/void PromptOn (struct pixel *myPixel)/ -<p> -<tt/void PromptOff (void)/ -<p> -The first function places a text prompt in given place and enables blinking. -The second one is pretty self-explanatory. - -<sect3>GetNextChar -<p> -<tt/char GetNextChar (void)/ -<p> -This function gets the next character from the keyboard queue. If the queue is empty it returns -<tt/NULL/, otherwise you receive the true ASCII code of a character or the value of a special (function) -key. See <tt/gsprite.h/ for the list of them. - -<sect1>Disk -<p> -This chapter covers rather low-level disk routines. You should use them with care, because -you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various -devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be -dangerous. -<p> -For some purposes you might consider using the <tt/dio.h/ interface to disk access. It is native. -<p> -All GEOS disk functions return an error code in the X register. In some cases this is returned by the -GEOSLib function (if its type is <tt/char/), but in all cases the last error is saved in the <tt/__oserror/ -location. If it is nonzero - an error occured. See <tt/gdisk.h/ for the list of possible errorcodes. -You need to include <tt/errno.h/ to get <tt/__oserror/, together with the standard <tt/errno/. The -latter gives less verbose, but still usable information and can be used with <tt/strerror/. -Probably you will get more information using <tt/_stroserror/ in a similar way. -<p> -For passing parameters use almost always a pointer to your data e.g. <tt/ReadBuff (&myTrSe)/. - -<sect2>Buffer functions -<p> -These functions take a single data sector (256 bytes) to read or write on the disk. - -<sect3>ReadBuff and Writebuff -<p> -<tt/char ReadBuff (struct tr_se *myTrSe)/ -<p> -<tt/char WriteBuff (struct tr_se *myTrSe)/ -<p> -These functions read and write a sector placed at <tt/diskBlkBuf/. - -<sect3>GetBlock and ReadBlock -<p> -<tt/char GetBlock (struct tr_se *myTrSe, char *buffer)/ -<p> -<tt/char ReadBlock (struct tr_se *myTrSe, char *buffer)/ -<p> -These two functions read a single block directly to the 256 byte array placed at <tt/buffer/. -The difference between them is that <tt/GetBlock/ initializes TurboDos in the drive if it was not -enabled. <tt/ReadBlock/ assumes that it is already enabled thus being slightly faster. - -<sect3>PutBlock, WriteBlock, VerWriteBlock -<p> -<tt/char PutBlock (struct tr_se *myTrSe, char *buffer)/ -<p> -<tt/char WriteBlock (struct tr_se *myTrSe, char *buffer)/ -<p> -<tt/char VerWriteBlock (struct tr_se *myTrSe, char *buffer)/ -<p> -Similar to previous but needed for writing the disk. <tt/VerWriteBlock/ verifies the data after -writing. In case of an error five tries are attempted before an error code is returned. - -<sect2>Directory header -<p> -The functions described here operate on <tt/curDirHeader/ where the current disk header is stored. -On larger (than 1541) capacity drives the second part of the directory header is in <tt/dir2Head/. - -<sect3>GetPtrCurDkNm -<p> -<tt/void GetPtrCurDkNm (char *diskName)/ -<p> -This function fills the given character string with the name of current disk. It is converted to C -standard - the string is terminated with <tt/NULL/ character instead of code 160 as in Commodore DOS. -Note that the passed pointer must point to an array of at least 17 bytes. - -<sect3>GetDirHead and PutDirHead -<p> -<tt/char GetDirHead (void)/ -<p> -<tt/char PutDirHead (void)/ -<p> -These functions read and write the directory header. You should use <tt/GetDirHead/ before -using any functions described below, and you should use <tt/PutDirHead/ to save the changes on the -disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/. - -<sect3>CalcBlksFree -<p> -<tt/unsigned CalcBlksFree (void)/ -<p> -This function returns the number of free blocks on the current disk. It is counted using data in -<tt/curDirHead/ so you must initialize the disk before calling it. - -<sect3>ChkDskGEOS -<p> -<tt/char ChkDskGEOS (void)/ -<p> -This functions checks <tt/curDirHead/ for the GEOS Format identifier. It returns either true or false, -and also sets <tt/isGEOS/ properly. You must initialize the disk before using this. - -<sect3>SetGEOSDisk -<p> -<tt/char SetGEOSDisk (void)/ -<p> -This function initializes disk for use with GEOS. It sets the indicator in directory header and -allocates a sector for the directory of border files. You don't need to initialize the disk before -using. - -<sect3>FindBAMBit -<p> -<tt/char FindBAMBit (struct tr_se *myTrSe)/ -<p> -This function returns the bit value from the BAM (Block Allocation Map) for the given sector. The bit is -set if the sector is free to use. The returned value is always zero if the sector is already allocated. -In fact, this function could be used in a following way: -<tscreen><verb> -#define BlockInUse FindBAMBit -... -if (!BlockInUse(&myTrSe)) { -... block not allocated ... -} -</verb></tscreen> -<p> -Anyway, I feel that this function is too low-level. - -<sect3>BlkAlloc and NxtBlkAlloc -<p> -<tt/char BlkAlloc (struct tr_se output[&rsqb, unsigned length)/ -<p> -<tt/char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[&rsqb, unsigned length)/ -<p> -Both functions allocate enough disk sectors to fit <tt/length/ bytes in them. You -find the output in <tt/output/ which is a table of <tt/struct tr_se/. The last entry will have the -track equal to 0 and sector equal to 255. The simplest way of using them is to use -predefined space in the GEOS data space and pass <tt/fileTrScTab/, which is a predefined table. -<p> -The difference between those two is that <tt/NextBlkAlloc/ starts allocating from the given sector, -and <tt/BlkAlloc/ starts from the first nonused sector. -<p> -You need to use <tt/PutDirHead/ later to save any changes in BAM. - -<sect3>FreeBlock -<p> -<tt/char FreeBlock (struct tr_se *myTrSe)/ -<p> -Simply deallocates a block in the BAM. You need to update the BAM with <tt/PutDirHead/. - -<sect3>SetNextFree -<p> -<tt/struct tr_se SetNextFree (struct tr_se *myTrSe)/ -<p> -This function finds the first free sector starting from given track and sector and allocates it. -It might return the same argument if the given block is not allocated. I wanted it to be type -clean, but this made the usage a bit tricky. To assign a value to your own <tt/struct tr_se/ you have to -cast both variables to <tt/unsigned/. E.g. -<tscreen><verb> -struct tr_se myTrSe; -... -(unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe); -</verb></tscreen> -<p> -In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/. -<p> -Note: you <em/must/ use casting to have the correct values. - -<sect2>Low-level disk IO -<p> -Functions described here are more usable in Kernal or drivers code, less common in applications, -but who knows, maybe someone will need them. - -<sect3>EnterTurbo, ExitTurbo, PurgeTurbo -<p> -<tt/void EnterTurbo (void)/ -<p> -<tt/void ExitTurbo (void)/ -<p> -<tt/void PurgeTurbo (void)/ -<p> -These functions are the interface to the GEOS TurboDos feature which makes slow Commodore drives a bit -more usable. <tt/EnterTurbo/ enables TurboDos unless it is already enabled. If not, then you will -have to wait a bit to transfer the TurboDos code into disk drive RAM. <tt/ExitTurbo/ disables TurboDos. -This is useful for sending some DOS commands to a drive e.g. for formatting. Note that before any -interaction with the Kernal in ROM you have to call <tt/InitForIO/. You don't have to worry about speed. -<tt/EnterTurbo/ will only enable TurboDos (no code transfer) if TurboDos was disabled with -<tt/ExitTurbo/. <tt/PurgeTurbo/ acts differently from <tt/ExitTurbo/ - it not only disables TurboDos, -but also removes it from drive RAM (not quite true, but it works like that). After using -<tt/PurgeTurbo/ the next call to <tt/EnterTurbo/ will reload drive RAM. - -<sect3>ChangeDiskDevice -<p> -<tt/char ChangeDiskDevice (char newDevice)/ -<p> -This function changes the device number of the current device (in fact drives only) to the given one. It is -usable for swapping drives. There's no check if the given <tt/newDevice/ already exist, so if you want -to change the logical number of drive 8 to 9 and you already have a drive number 9 then GEOS will probably -hang on disk access. Use safe, large numbers. Note that the safe IEC range is 8-30. - -<sect2>Disk Initialization -<p> -GEOS has two functions for initialization ('logging in' as they say on CP/M) of a disk. -<sect3>OpenDisk -<p> -<tt/char OpenDisk (void)/ -<p> -This function initializes everything for a new disk. It loads and enables TurboDos if needed. -Then the disk is initialized with <tt/NewDisk/. Next, <tt/GetDirHead/ initializes <tt/curDirHead/. -Disk names are compared and if they differ then the disk cache on REU is cleared. Finally the format is -checked with <tt/ChkDkGEOS/ and the disk name is updated in the internal tables. - -<sect3>NewDisk -<p> -<tt/char NewDisk (void)/ -<p> -This function is similar to the DOS command I. It clears the REU cache and enables TurboDos if needed. - -<sect1>Files -<p> -This section covers the GEOS file interface. - -<sect2>Directory handling -<p> -The functions described here are common for SEQ and VLIR structures. - -<sect3>Get1stDirEntry and GetNxtDirEntry -<p> -<tt/struct filehandle *Get1stDirEntry (void)/ -<p> -<tt/struct filehandle *GetNxtDirEntry (void)/ -<p> -These two functions are best suited for scanning the whole directory for particular files. Note that -the returned filehandles describe all file slots in the directory - even those with deleted files. -The return value can be obtained by casting both sides to <tt/unsigned/ - as in the <tt/SetNextFree/ -function or read directly after a call to those two functions from <tt/r5/. The current sector number -is in <tt/r1/ and the sector data itself is in <tt/diskBlkBuf/. - -<sect3>FindFile -<p> -<tt/char FindFile (char *fName)/ -<p> -This function scans the whole directory for the given filename. It returns either 0 (success) or 5 -(FILE_NOT_FOUND, defined in <tt/gdisk.h/) or any other fatal disk read error. After a successful -<tt/FindFile/ you will have <tt/struct filehandle/ at <tt/dirEntryBuf/ filled with the file's data and -other registers set as described in <tt/GetNxtDirEntry/. - -<sect3>FindFTypes -<p> -<tt/char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)/ -<p> -This function scans the directory and fills a table at <tt/buffer/ with <tt/char [17]/ entries. -<tt/fType/ is the GEOS type of the searched files and <tt/classTxt/ is a string for the Class field in the file -header. Class matches if the given string is equal or shorter than that found in the file's header block. -If you want just to find all files with the given GEOS type you should pass an empty string or <tt/NULL/ as -<tt/classTxt/. Be warned that for searching <tt/NON_GEOS/ files you must pass <tt/NULL/ as <tt/classTxt/. -<tt/fMaxNum/ is the maximal number of files to find, thus the <tt/buffer/ must provide an area of size -equal to <tt/17 * fMaxNum/. This function returns the number of found files, ranging from 0 to number -passed as <tt/fMaxNum/. The return value can be also restored from <tt/r7H/. - -<sect3>DeleteFile -<p> -<tt/char DeleteFile (char *fName)/ -<p> -This function deletes a file by its name. It works for SEQ and VLIR files. - -<sect3>RenameFile -<p> -<tt/char RenameFile (char *oldName, char *newName)/ -<p> -I think it is obvious... - -<sect3>GetFHdrInfo -<p> -<tt/char GetFHdrInfo (struct filehandle *myFile)/ -<p> -This function loads the file header into the <tt/fileHeader/ buffer. Using after e.g. <tt/FindFile/ -you can pass the address of <tt/dirEntryBuf/. - -<sect2>Common and SEQ structure -<p> -Functions described here are common for SEQ and VLIR structures because the arguments passed are the -starting track and sector which may point either to the start of a chain for VLIR or the data for SEQ. - -<sect3>GetFile -<p> -<tt/char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)/ -<p> -This routine loads and runs a given file <tt/fname/. The file must be one of following types: -<tt/SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER,/ or <tt/INPUT_DEVICE/. The execution -address is taken from the file header. If it is zero, then the file is only loaded. Only the first chain -from VLIR files is loaded. If <tt/flag/ has bit 0 set then the load address is taken from <tt/loadaddr/ -and not from the file header. In this case <tt/APPLICATION/ files will be only loaded, not executed. -This does not apply to <tt/DESK_ACC/. If either bit 6 or 7 of <tt/flag/ are set, then 16 bytes from -<tt/datadname/ are copied to <tt/dataDiskName/ and 16 bytes from <tt/datafname/ go to <tt/dataFileName/ -thus becoming parameters for the new application. Pass <tt/NULL/ for any unused parameter. - -<sect3>ReadFile -<p> -<tt/char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)/ -<p> -This function reads at most <tt/fLength/ bytes into <tt/buffer/ from chained sectors starting at -<tt/myTrSe/. - -<sect3>ReadByte -<p> -<tt/char ReadByte (void)/ -<p> -This function returns the next byte from a file. Before the first call to it you must load <tt/r5/ -with <tt/NULL/, <tt/r4/ with the sector buffer address and <tt/r1/ with the track and sector of the -first block of a file. -Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/. These registers must be preserved between -calls to <tt/ReadByte/. -<p> -The returned value is valid only if there was no error. The end of file is marked as <tt/BFR_OVERFLOW/ -in <tt/__oserror/, this is set when trying to read one byte after the end of file, in this case the -returned value is invalid. - -<sect3>SaveFile -<p> -<tt/char SaveFile (char skip, struct fileheader *myHeader)/ -<p> -<tt/SaveFile/ will take care of everything needed to create a GEOS file, no matter if VLIR of SEQ -structure. All you need to do is to place the data in the proper place and prepare a header which will -contain all information about a file. The <tt/skip/ parameter says how many directory pages you -want to skip before searching for a free slot for the directory entry. In most cases you will put -<tt/0/ there. -<p> -You have to declare a <tt/struct fileheader/ and fill it with proper values. There is only one -difference - the first two bytes which are a link to a nonexistent next sector are replaced by a -pointer to the DOS filename of the file. -<p> -When saving sequential files the two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/ -and <tt/fileheader.end_address/. - -<sect3>FreeFile -<p> -<tt/char FreeFile (struct tr_se myTable[])/ -<p> -This function deallocates all sectors contained in the passed table. - -<sect3>FollowChain -<p> -<tt/char FollowChain(struct tr_se *myTrSe, char *buffer)/ -<p> -This function fills a <tt/struct tr_se/ table at <tt/buffer/ with the sector numbers for a chain of -sectors starting with <tt/myTrSe/. You can pass such data (<tt/buffer/) to e.g. <tt/FreeFile/. - -<sect2>VLIR structure -<p> -Here is information about VLIR files (later called RecordFiles) and functions. -<p> -A VLIR structure file consists of up to 127 SEQ-like files called records. Each record is like one -SEQ structure file. Records are grouped together, described by a common name - the VLIR file name and -an own number. Each record pointed to by its number is described by the starting track and sector numbers. -VLIR structures allow records to be empty (<tt/tr_se/ of such record is equal to <tt/{NULL,$ff}/), -or even non-exist (<tt/{NULL,NULL}/). Any other numbers represent the starting track and sector of -a particular file. -<p> -In GEOS there can be only one file opened at a time. Upon opening a VLIR file some information -about it is copied into memory. You can retrieve the records table at <tt/fileTrScTab/ (table of -128 <tt/struct tr_se/) and from <tt/VLIRInfo/ (<tt/struct VLIR_info/. -E.g. the size of whole VLIR file can be retrieved by reading <tt/VLIRInfo.fileSize/. - -<sect3>OpenRecordFile -<p> -<tt/char OpenRecordFile (char *fName)/ -<p> -This function finds and opens a given file. An error is returned if the file is not found or if it is not -in VLIR format. Information in <tt/VLIRInfo/ is initialized. VLIR track and sector table is -loaded at <tt/fileTrScTab/ and will be valid until a call to <tt/CloseRecordFile/ so don't modify it. -You should call <tt/PointRecord/ before trying to do something with the file. - -<sect3>CloseRecordFile -<p> -<tt/char CloseRecordFile (void)/ -<p> -This function calls <tt/UpdateRecordFile/ and clears internal GEOS variables. - -<sect3>UpdateRecordFile -<p> -<tt/char UpdateRecordFile (void)/ -<p> -This function will check the <tt/VLIRInfo.fileWritten/ flag and if it is set, then <tt/curDirHead/ is -updated along with size and date stamps in the directory entry. - -<sect3>PointRecord -<p> -<tt/char PointRecord (char recordNumber)/ -<p> -This function will setup internal variables (and <tt/VLIRInfo.curRecord/) and return the track and -sector of the given record in <tt/r1/. Note that the data may not be valid (if the record is non-existing -you will get 0,0 and if it is empty - 255,0). - -<sect3>NextRecord and PreviousRecord -<p> -<tt/char NextRecord (void)/ -<p> -<tt/char PreviousRecord (void)/ -<p> -These two work like <tt/PointRecord/. Names are self-explanatory. - -<sect3>AppendRecord -<p> -<tt/char AppendRecord (void)/ -<p> -This function will append an empty record (pair of 255,0) to the current VLIR track and sector -table. It will also set <tt/VLIRInfo.curRecord/ to its number. - -<sect3>DeleteRecord -<p> -<tt/char DeleteRecord (void)/ -<p> -This function will remove the current record from the table, and move all current+1 records one place -back (in the table). Note that there's no BAM update and you must call <tt/UpdateRecordFile/ to -commit changes. - -<sect3>InsertRecord -<p> -<tt/char InsertRecord (void)/ -<p> -This function will insert an empty record in place of <tt/VLIRInfo.curRecord/ and move all following -records in the table one place forward (contents of <tt/VLIRInfo.curRecord/ after a call to <tt/InsertRecord/ -can be found in <tt/VLIRInfo.curRecord + 1/). - -<sect3>ReadRecord and WriteRecord -<p> -<tt/char ReadRecord (char *buffer, unsigned fLength)/ -<p> -<tt/char WriteRecord (char *buffer, unsigned fLength)/ -<p> -This function will load or save at most <tt/fLength/ bytes from the currently pointed record into or from -<tt/buffer/. - -<sect1>Memory and Strings -<p> -The functions covered in this section are common for the whole C world - copying memory parts and -strings is one of the main computer tasks. GEOS also has an interface to do this. These functions -are replacements for those like <tt/memset, memcpy, strcpy/ etc. from standard libraries. -If you are dealing with short strings (up to 255 characters) you should use these functions -instead of standard ones, e.g. <tt/CopyString/ instead of <tt/strcpy/. It will work faster. -<p> -However some of them have slightly different calling conventions (order of arguments to be specific), -so please check their syntax here before a direct replacement. -<p> -Please note that the memory areas described here as <em/strings/ are up to 255 characters (without -counting the terminating <tt/NULL/), and <em/regions/ can cover the whole 64K of memory. - -<sect2>CopyString -<p> -<tt/void CopyString (char *dest, char *src)/ -<p> -This function copies the string from <tt/src/ to <tt/dest/, until it reaches <tt/NULL/. The <tt/NULL/ -is also copied. - -<sect2>CmpString -<p> -<tt/char CmpString (char *s1, char *s2)/ -<p> -This function compares the strings <tt/s1/ to <tt/s2/ for equality - this is case sensitive, and both -strings have to have the same length. It returns either <tt/true/ (non-zero) or <tt/false/ (zero). - -<sect2>CopyFString and CmpFString -<p> -<tt/void CopyFString (char length, char *dest, char *src)/ -<p> -<tt/char CmpFString (char length, char *s1, char *s2)/ -<p> -These two are similar to <tt/CopyString/ and <tt/CmpString/ except the fact, that you provide -the length of the copied or compared strings. The strings can also contain several <tt/NULL/ -characters - they are not treated as delimiters. - -<sect2>CRC -<p> -<tt/unsigned CRC (char *src, unsigned length)/ -<p> -This function calculates the CRC checksum for the given memory range. I don't know if it is -compatible with standard CRC routines. - -<sect2>FillRam and ClearRam -<p> -<tt/void *FillRam (char *dest, char value, unsigned length)/ -<p> -<tt/void *ClearRam (char *dest, unsigned length)/ -<p> -Both functions are filling the given memory range. <tt/ClearRam/ fills with <tt/0s/, while -<tt/FillRam/ uses the given <tt/value/. Be warned that these functions destroy <tt/r0, r1 and -r2L/ registers. The functions are aliases for <tt/memset/ and <tt/bzero/, respectively. - -<sect2>MoveData -<p> -<tt/void *MoveData (char *dest, char *src, unsigned length)/ -<p> -This functions copies one memory region to another. There are checks for an overlap and the -non-destructive method is chosen. Be warned that this function destroys contents of the -<tt/r0, r1 and r2/ registers. This function is an alias for <tt/memcpy/. - -<sect2>InitRam -<p> -<tt/void InitRam (char *table)/ -<p> -This function allows to initialize multiple memory locations with single bytes or strings. -This is done with a <tt/table/ where everything is defined. See the structures chapter for a description of -<tt/InitRam's/ command string. - -<sect2>StashRAM, FetchRAM, SwapRAM, and VerifyRAM -<p> -<tt/void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ -<p> -<tt/void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ -<p> -<tt/void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ -<p> -<tt/ char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ -<p> -These functions are the interface to a REU - Ram Expansion Unit. I think that they are self-explanatory. -You can check for REU presence by taking the value of <tt/ramExpSize/. You have to do it before -using any of these functions. - -<sect1>Processes and Multitasking -<p> -Weird? Not at all. GEOS has some limited multitasking ability. You can set up a chain of functions -called in specified intervals and you can put the main program to sleep without disturbing other -tasks and making the user interface unresponsive. - -<sect2>InitProcesses -<p> -<tt/void InitProcesses (char number, struct process *processTab)/ -<p> -This is the main initialization routine. After calling it processes are set up, but not -enabled. The parameters for <tt/InitProcesses/ are: -<itemize> - <item><tt/number/ - number of processes - <item><tt/processTab/ - a table of <tt/struct process/, with size equal to <tt/number/ -</itemize> -<p> -A single task is described by an entry in <tt/processTab/, it contains two values - a <tt/pointer/ to -the task function and a number of <tt/jiffies/ which describe the delay between calls to task. On PAL -systems there are 50 jiffies per second, while on NTSC there are 60. -<p> -The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and -if <tt/processTab/ would be too large it would overwrite existing data in GEOS space. -<p> -There's one important thing - the last entry in <tt/processTab/ has to be <tt/NULL,NULL/, so the -maximum size of <tt/processTab/ is equal to 21. -<p> -See the description of <tt/process/ structure for a more detailed discussion on this. - -<sect2>RestartProcess and EnableProcess -<p> -<tt/void RestartProcess (char processNumber)/ -<p> -<tt/void EnableProcess (char processNumber)/ -<p> -These two functions start the task counter. <tt/RestartProcess/ should be called for each process -after <tt/InitProcesses/, because it resets all flags and counters and it starts the counters. -<p> -<tt/RestartProcess/ enables the counters and sets their initial value to that given in <tt/processTab/. -<p> -<tt/EnableProcess/ forces the given process to execute by simulating the timer expiring. - -<sect2>BlockProcess and UnblockProcess -<p> -<tt/void BlockProcess (char processNumber)/ -<p> -<tt/void UnblockProcess (char processNumber)/ -<p> -<tt/BlockProcess/ disables the execution of the given process, but this does not disable the timers. -It means that if you call <tt/UnblockProcess/ before the timer runs out, the process will be executed. -<p> -<tt/UnblockProcess/ does the opposite. - -<sect2>FreezeProcess and UnfreezeProcess -<p> -<tt/void FreezeProcess (char processNumber)/ -<p> -<tt/void UnfreezeProcess (char processNumber)/ -<p> -<tt/FreezeProcess/ disables timer for given process. <tt/UnfreezeProcess/ does the opposite. -This is not equal to <tt/RestartProcess/ as timers are not reloaded with initial value. - -<sect2>Sleep -<p> -<tt/void Sleep (unsigned jiffies)/ -<p> -This function is a multitasking sleep - the program is halted, but it doesn't block other functions -e.g. callbacks from menus and icons. -The only argument here is the number of jiffies to wait until the app will wake up. It depends on the -video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively). -If you don't want to worry about it and need only full second resolution, call the standard -<tt/sleep/ function from <tt/unistd.h/. - -<sect1>System Functions - -<sect2>FirstInit -<p> -<tt/void FirstInit (void)/ -<p> -This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot -up. You shouldn't use this unless you know what you are doing. - -<sect2>InitForIO and DoneWithIO -<p> -<tt/void InitForIO (void)/ -<p> -<tt/void DoneWithIO (void)/ -<p> -These functions are called by some disk routines. You should call them only if you want to -do something with IO registers or call one of the Kernal ROM routines. Note that this is rather an -expensive way of turning off IRQs and enabling IO. - -<sect2>MainLoop -<p> -<tt/void MainLoop (void)/ -<p> -Returns control to the system. Any code between call to <tt/MainLoop/ and the end of current -function will never be executed. When in <tt/MainLoop/ the system waits for your action - using -icons, keyboard or menus to force some specific action from the program. You have to define -proper handlers before that. - -<sect2>EnterDeskTop -<p> -<tt/void EnterDeskTop (void)/ -<p> -This is an alias for <tt/exit(0)/ so you will never burn yourself. Anyway, you should not -use it. Always use <tt/exit()/ instead. Library destructors and functions registered with -<tt/atexit()/ are called. - -<sect2>ToBASIC -<p> -<tt/void ToBASIC (void)/ -<p> -This one is another way of terminating an application - forcing GEOS to shutdown and exit to BASIC. -I was considering whether to include it or not, but maybe someone will need it - which I doubt. -<p> -<em/WARNING:/ library destructors and functions registered with <tt/atexit()/ will not be called -so it is quite unsafe way to terminate your program. - -<sect2>Panic -<p> -<tt/void Panic (void)/ -<p> -This calls system's <tt/Panic/ handler - it shows a dialog box with the message -<tscreen><verb> -System error at:xxxx -</verb></tscreen> -where <tt/xxxx/ is last known execution address (caller). By default this is bound to the <tt/BRK/ -instruction, but it might be usable in debugging as kind of <tt/assert/. (Note that <tt/assert/ -is available as a separate function and will give you more information than that). -<p> -The system is halted after a call to <tt/Panic/ which means that library destructors will not be -called and some data may be lost (no wonder you're panicking). - -<sect2>CallRoutine -<p> -<tt/void CallRoutine (void *myFunct)/ -<p> -This is a system caller routine. You need to provide a pointer to a function and it will be immediately -called, unless the pointer is equal to <tt/NULL/. This is the main functionality of this function - -you don't need to check if the pointer is valid. - -<sect2>GetSerialNumber -<p> -<tt/unsigned GetSerialNumber (void)/ -<p> -This function returns the serial number of the system. It might be used for copy-protection. -However, please remember that Free Software is a true power and you are using it right now. - -<sect2>GetRandom -<p> -<tt/char GetRandom (void)/ -<p> -This function returns a random number. It can be also read from <tt/random/ e.g. -<tscreen><verb> -a=random; -</verb></tscreen> -but by calling this function you are sure that the results will be always different. -<tt/random/ is updated once a frame (50Hz PAL) and on every call to <tt/GetRandom/. -<p> -Note that this is not the same as the <tt/rand/ function from the standard library. <tt/GetRandom/ -will give you unpredictable results (if IRQs occur between calls to it) while -<tt/rand/ conforms to the standard and for a given seed (<tt/srand/) always returns with the -same sequence of values. - -<sect2>SetDevice -<p> -<tt/void SetDevice (char device)/ -<p> -This function sets the current device to the given. It might be used together with <tt/InitForIO/, -<tt/DoneWithIO/ and some Kernal routines. Unless the new device is a disk drive this only sets -new value in <tt/curDevice/, in the other case new disk driver is loaded from REU or internal RAM. - -<sect2>get_ostype -<p> -<tt/char get_ostype (void)/ -<p> -This function returns the GEOS Kernal version combined (by logical OR) with the machine type. Read -<tt/gsys.h/ for definitions of the returned values. - -<sect2>get_tv -<p> -<tt/char get_tv (void)/ -<p> -This function returns the PAL/NTSC flag combined (by logical OR) with the 40/80 columns flag. This is -not the best way to check if the screen has 40 or 80 columns since a PAL/NTSC check is always -performed and it can take as long as a full raster frame. If you just want to know if the -screen has 40 or 80 columns use the expression <tt/graphMode & 0x80/ which returns <tt/0/ for -40 columns and <tt/0x80/ for 80 columns. Remember that this value can be changed during -runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test -anything if not running under GEOS128. Use <tt/get_ostype/ to check it. Read <tt/gsys.h/ for -definitions of the returned values. - -<sect>Library Structures -<p> -To simplify usage and optimize passing parameters to functions I have declared several structures -which describe the most common objects. Some of these structures are bound to static addresses in -the GEOS data space (<tt/$8000-$8fff/), so you can use their fields directly in an optimized way. -Please see <tt/gsym.h/ to find them. All structures are defined in <tt/gstruct.h/ and you may -find also some comments there. - -<sect1>Graphics Structures - -<sect2>pixel -<p> -A simple structure describing a point on the screen. - -<sect2>fontdesc -<p> -This structure describes a font in one pointsize. There is the current font - <tt/struct fontdesc/ -bound to <tt/curFontDesc/. You can also force GEOS to use your own fonts by calling -<tt/LoadCharSet/. You just need to open a VLIR font file and load one record - one pointsize - -somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can -pass a pointer to the load address of that pointsize to <tt/LoadCharSet/. (Note that although -it has 'Load' in the name, that function loads only GEOS internal data structures, not data -from disk). - -<sect2>window -<p> -This widely used structure holds the description of a region of the screen. It describes the top-left and -bottom-right corners of a window. - -<sect2>iconpic -<p> -Maybe the name isn't the best - it has nothing with <tt/DoIcons/ but with bitmap functions - -<tt/BitmapUp/ for example. This structure holds the parameters needed to properly decode and show -a bitmap on the screen. The bitmap has to be encoded - if you have some non-GEOS bitmaps simply -convert them to Photo Scraps - this is the format used by all GEOS bitmap functions - <tt/DoIcons/ -too. - -<sect1>Icons -<p> -These structures describe click boxes (icons) that can be placed on screen or in a dialog box. - -<sect2>icondef -<p> -This is the definition of a single click box. Please see <tt/gstruct.h/ for a description of its fields. - -<sect2>icontab -<p> -This is the toplevel description of icons to be placed and enabled on the screen. This structure -has the following fields: -<itemize> - <item><tt/char number/ - total number of icons declared here - <item><tt/struct pixel mousepos/ - after finishing <tt/DoIcons/ the mouse pointer will be placed in - this point allowing you to have a hint for the user what the default action is - <item><tt/struct icondef tab[&rsqb/ - this table of size equal to <tt/icontab.number/ contains - descriptions for all icons -</itemize> - -<sect1>File and Disk - -<sect2>tr_se -<p> -This simple structure holds the track and sector number of something. Do not expect the track to be -in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K -expansion is utilized as RAMDisk with a layout of 4 tracks of 128 sectors each. However assuming that -a track number equal to 0 is illegal might be wise. - -<sect2>f_date -<p> -This is a placeholder for a file datestamp. This structure is also present in <tt/struct filehandle/. -GEOS is not Y2K compliant, so if the current file has in <tt/filehandle.date.year/ a value less than 86 -you can safely assume that it is e.g. 2004 and not 1904. - -<sect2>filehandle -<p> -This is the main file descriptor. It is either an entry in the directory (returned from file functions) -or its copy in <tt/dirEntryBuf/. This is optimized so you can safely get to the file's year e.g. -by testing <tt/dirEntryBuf.date.year/ - it will be compiled to simple <tt/LDA, STA/. - -<sect2>fileheader -<p> -This structure holds the fileheader description. You can load a file's header into the <tt/fileHeader/ -fixed area using <tt/GetFHdrInfo/. (note that <tt/fileHeader/ is a place in memory while -<tt/fileheader/ is a structure). -You will also need your own fileheader for <tt/SaveFile/. - -<sect1>System Structures - -<sect2>s_date -<p> -This structure is defined only for <tt/system_date/. It is slightly different from <tt/f_date/ -so I prepared this one. You can e.g. get or set the current time using <tt/system_date.s_hour/ and -<tt/system_date.s_minute/. Accesses to these will be optimized to simple <tt/LDA/ and <tt/STA/ -pair. - -<sect2>process -<p> -You should declare a table of that type to prepare data for <tt/InitProcesses/. The maximum number -of processes is 20, and the last entry has to be equal to <tt/{NULL,NULL}/, so this table may hold -only 21 entries. The first member of this structure (<tt/pointer/) holds the pointer to the called -function (void returning void), you will probably have to cast that pointer into <tt/unsigned int/. -The second field <tt/jiffies/ holds the amount of time between calls to that function. -On PAL systems there are 50 jiffies per second, while NTSC have 60 of them. - -<sect1>A few things in detail... -<p> -GEOSLib uses cc65 non-ANSI extensions to easily initialize data in memory. This is done with a -kind of array of unspecified length and unspecified type. Here is how it works: -<tscreen><verb> -void example = { - (char)3, (unsigned)3, (char)0 }; -</verb></tscreen> -Which will be compiled to following string of bytes: -<tscreen><verb> -_example: - .byte 3 - .word 3 - .byte 0 -</verb></tscreen> -As you see this way it is possible to define data of any type in any order. You must remember to -cast each member to proper type. - -<sect2>DoMenu structure -<p> -<tt/DoMenu/ is responsible for everything concerned with menu processing. Many, many GEOS programs -are just initializing the screen and menu and returning to <tt/MainLoop/. In GEOSLib it is the same as -returning from <tt/main/ function without using <tt/exit(0)/. -<p> -A menu is described by two types of data - menu descriptors and menu items. A descriptor contains -information about the following menu items, and items contain names of entries and either -pointers to functions to execute or, in case of nested menus, pointers to submenu descriptors. -Note that submenu descriptor can be top-level descriptor, there's no difference in structure, -just in the content. -<p> -Here is how a single descriptor looks like: -<tscreen><verb> -void myMenu = { - (char)top, (char)bottom, // this is the size of the menubox - (unsigned)left, (unsigned)right, // counting all items in the current descriptor - (char)number_of_items | type_of_menu, // number of following items ORed with - // type of this menu, it can be either - // HORIZONTAL or VERTICAL if you will have also bit 6 set then menu won't be closed - // after moving mouse pointer outside the menubox. You can have at most 31 items. -</verb></tscreen> -This is followed by <tt/number_of_items/ of following item description. -<tscreen><verb> - ... - "menuitemname", (char)item_type, (unsigned)pointer, - "nextitemname", (char)item_type, (unsigned)pointer, - ... - "lastitemname", (char)item_type, (unsigned)pointer }; - // Note that there isn't ending <tt/NULL/ or something like that. -</verb></tscreen> -<tt/pointer/ is a pointer to something, what it points for depends from <tt/item_type/. This one -can have following values: -<p> -<tt/MENU_ACTION/ - a function pointed by <tt/pointer/ will be called after clicking on the menu item -<p> -<tt/SUB_MENU/ - <tt/pointer/ points to next menu descriptor - a submenu -<p> -Both of them can be ORed with <tt/DYN_SUB_MENU/ and then the <tt/pointer/ points to a function -which will return in <tt/r0/ the needed pointer (to function to execute or a submenu). -<p> -For creating nested menus (you can have at most 8 levels of submenus) you need to declare such -a structure for each submenu and top level menu. - -<sect2>DoDlgBox command string -<p> -<tt/DoDlgBox/ is together with <tt/DoMenu/ one of the most powerful routines in GEOS. It is -responsible for creating dialog boxes, that is windows which task is to interact with the user. -The format of the command string is following: -<tscreen><verb> - (window size and position) - (commands and parameters) - NULL -</verb></tscreen> -There is a custom type defined for the command string: <tt/dlgBoxStr/. - -<sect3>Size and position -<p> -The first element can be specified in two ways - by using the default size and position or specifying -your own. The first case results in -<tscreen><verb> -const dlgBoxStr example = { - DB_DEFPOS (pattern_of_shadow), - ... // commands - DB_END }; -</verb></tscreen> -And the own size and position would be: -<tscreen><verb> -const dlgBoxStr example = { - DB_SETPOS (pattern, top, bottom, left, right) - ... // commands - DB_END }; -</verb></tscreen> - -<sect3>Commands -<p> -The next element of the <tt/DoDlgBox/ command string are the commands themselves. The first six commands are -default icons and the number of the selected icon will be returned from window processor. The icons are -<tt/OK, CANCEL, YES, NO, OPEN/, and <tt/DISK/. You can use predefined macros for using them, e.g.: -<tscreen><verb> - ... - DB_ICON(OK, DBI_X_0, DBI_Y_0), - ... -</verb></tscreen> -Note that the position is counted from top left corner of window, not entire screen and that the 'x' -position is counted in cards (8-pixel) and not in pixels. This is also true for all following commands. -<tt/DBI_X_0/ and <tt/DBI_Y_0/ are predefined (see <tt/gdlgbox.h/ for more), the default positions -which will cause icons to appear on a default window exactly where you would expect them. -<p> -<tt/DB_TXTSTR (x, y, text)/ will cause to show the given text in the window. -<p> -<tt/DB_VARSTR (x, y, ptr)/ works as above, but here you are passing a pointer to a zero page location -where the address of the text is stored. This is useful for information windows where only the text content -is variable. Consider following: -<tscreen><verb> -char text = "foo"; - ... - r15=(unsigned)text; // in code just before call to DoDlgBox - ... - DB_VARSTR (TXT_LN_X, TXT_LN_1_Y, &r15), - ... -</verb></tscreen> -will cause the word ``foo'' to appear in the window, but you may store the pointer to any text in -<tt/r15/ (in this case) before the call to DoDlgBox. -<p> -<tt/DB_GETSTR(x, y, ptr, length)/ - will add a input-from-keyboard feature. <tt/ptr/ works as in the -previous example and points to the location where the text is to be stored. Note that the contents of this -location will be shown upon creating the window. <tt/length/ is the maximum number of characters to input. -<p> -<tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to the given pointer. It is called on every keypress. -<p> -<tt/DB_GRPHSTR(ptr)/ - the data for this command is a pointer for <tt/GraphicsString/ commands. -<p> -<tt/DB_GETFILES(x, y)/ - for a standard window you should pass 4 for both x and y. This function -draws a file selection box and searches the current drive for files. Before the call to <tt/DoDlgBox/ you -must load <tt/r7L/ with the GEOS filetype of searched files and <tt/r10/ with the class text. In <tt/r5/ -you have to load a pointer to a <tt/char[17]/ where the selected filename will be copied. It works -like <tt/FindFTypes/ but is limited to first 16 files. -<p> -<tt/DB_OPVEC(ptr)/ - this sets a new pointer for the button press function, if you pass -<tt/RstrFrmDialogue/ here you will cause the window to close after pressing mouse button. -<p> -<tt/DB_USRICON(x, y, ptr)/ - places a single user icon (click box) on the window, <tt/ptr/ points at a -<tt/struct icondef/ but fields <tt/x/ and <tt/y/ are not used here. You can have at most 8 click -boxes in a window, this is an internal limit of the GEOS Kernal. -<p> -<tt/DB_USRROUT(ptr)/ - this command causes to immediately call the user routine pointed by <tt/ptr/. - -<sect2>GraphicsString command string -<p> -<tt/GraphicsString/ is a very powerful routine to initialize the whole screen at once. There are -predefined macros for all commands, names are self-explanatory, see them in <tt/ggraph.h/. The last -command has to be <tt/GSTR_END/. There is a custom type defined for the command string: <tt/graphicStr/. -<p> -Here is an example for clearing the screen: -<tscreen><verb> -const graphicStr example = { - MOVEPENTO(0,0), - NEWPATTERN(0), - RECTANGLETO(319,199) - GSTR_END }; -</verb></tscreen> - -<sect2>InitRam table -<p> -This type of data is used to initialize one or more bytes in different locations at once. The format is -the following: -<tscreen><verb> -void example = { - (unsigned)address_to_store_values_at, - (char)number_of_bytes_that_follow, - (char)data,(char)data (...) - // more such definitions - (unsigned)NULL // address of 0 ends the table - }; -</verb></tscreen> - -<sect2>Intercepting system vectors -<p> -It is possible to intercept events and hook into the GEOS Kernal using vectors. Here is a little example: -<tscreen><verb> -void_func oldVector; - -void NewVectorHandler(void) { - // do something and at the end call the old vector routine - oldVector(); -} - -void hook_into_system(void) { - oldVector = mouseVector; - mouseVector = NewVectorHandler; -} - -void remove_hook(void) { - mouseVector = oldVector; -} -</verb></tscreen> -<p> -In your <tt/main/ function you should call <tt/hook_into_system()/ but <em/after/ all calls to the GEOS -Kernal (like <tt/DoMenu/, <tt/DoIcons/, etc.) - right before passing control to the <tt/MainLoop()/. -Be warned that vectors are most likely to be changed by the GEOS Kernal also via other functions (like -<tt/GotoFirstMenu/, <tt/DoDlgBox/ and its derivatives etc.). It depends on what Kernal functions -you use and which vectors you altered. Unfortunately there is no exact list for GEOS 2.0, a complete -list for GEOS 1.x can be found in A. Boyce's Programmers' Reference Guide mentioned before. Most of the -information contained there should be still valid for GEOS 2.0. When calling a function that restores -the vector you should add a <tt/hook_into_system()/ call right after it. -<p> -It is critical to restore old vector values before exiting the program. If you have more than one -place where you call <tt/exit()/ then it might be worth to register <tt/remove_hook/ function to -be called upon exiting with <tt/atexit(&remove_hook);/ call. This way you will ensure that -such destructor will be always called. -<p> -That little example above intercepts <tt/mouseVector/. The <tt/NewVectorHandler/ function will be -called every time the mouse button changes status. Other important vectors you should know about -are: -<itemize> - <item><tt/appMain/ - this is called from within the <tt/MainLoop/ system loop - <item><tt/keyVector/ - called whenever a keypress occurs - <item><tt/intTopVector/ - called at the start of the IRQ routine - <item><tt/intBotVector/ - called at the end of the IRQ routine -</itemize> - -</article> diff --git a/doc/grc65.sgml b/doc/grc65.sgml deleted file mode 100644 index 583c6f80f..000000000 --- a/doc/grc65.sgml +++ /dev/null @@ -1,392 +0,0 @@ -<!doctype linuxdoc system> -<article> - -<!-- Title information --> - -<title>grc65 -- GEOS Resource Compiler -<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl"> -<and><url name="Greg King" url="mailto:gngking@erols.com"> -<date>VII 2000; VI,VII 2002; 2005-8-3 -<abstract> -This document describes a compiler that can create GEOS headers and menues for -cc65-compiled programs. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview -<p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to -generate required and optional resources. A required resource for every GEOS -application is the header, that is: an icon, some strings, and some addresses. -Optional resources might be menu definitions, other headers (e.g., for data -files of an app.), dialog definitions, etc. Without an application's header, -GEOS is unable to load and start it. - -Currently, <bf/grc65/ supports only menues and the required header definition, -along with support for building applications with VLIR-structured overlays. - -<bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s). -That is because the application header data must be in assembly format, while -the menu definitions can be translated easily into C. The purpose of the C -file is to include it as a header in only one project file. The assembly source -should be processed by <bf/ca65/ and linked to the application (read about -<ref name="the building process" id="building-seq">). - - - -<sect>Usage -<p>grc65 accepts the following options: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: grc65 [options] file -Short options: - -V Print the version number - -h Help (this text) - -o name Name the C output file - -s name Name the asm output file - -t sys Set the target system - -Long options: - --help Help (this text) - --target sys Set the target system - --version Print the version number ---------------------------------------------------------------------------- -</verb></tscreen> -Default output names are made from input names with extensions replaced by -<tt/.h/ and <tt/.s/. - - - -<sect>Resource file format -<p>A resource file has the name extension <tt/.grc/. That is not required, but -it will make for an easier recognition of the file's purpose. Also, <bf/cl65/ -recognizes those files. <bf/grc65/'s parser is very weak at the moment; so, -read the comments carefully, and write resources exactly as they are written -here. Look out for CAPS and small letters. Everything after a '<tt/;/' -until the end of the line is considered as a comment and ignored. See the -included <ref name="commented example .grc file" id="example-grc"> for a -better view of the situation. - - -<sect1>Menu definition -<p><tscreen><verb> -MENU menuName leftx,topy <ORIENTATION> { - "item name 1" <MENU_TYPE> pointer - ... - "item name x" <MENU_TYPE> pointer -}</verb></tscreen> -The definition starts with the keyword <tt/MENU/, then comes the menu's name, -which will be represented in C as <tt/const void/. Then are the co-ordinates -of the top left corner of the menu box. The position of the bottom right -corner is estimated, based on the length of item names and the menu's -orientation. It means that the menu box always will be as large as it should -be. Then, there's the orientation keyword; it can be either <tt/HORIZONTAL/ or -<tt/VERTICAL/. Between <tt/{/ and <tt/}/, there's the menu's -content. It consists of item definitions. First is an item name -- it has to -be in quotes. Next is a menu-type bit. It can be <tt/MENU_ACTION/ or -<tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit -(see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of -them). You can use C logical operators in expressions, but you have to do it -without spaces. So a dynamically created submenu will be something like: -<tscreen><verb> -"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen> -The last part of the item definition is a pointer which can be any name that is -present in the C source code that includes the generated header. It can point -to a function or to another menu definition. - -If you are doing sub(sub)menu definitions, remember to place the lowest level -definition first, and the top-level menu as the last one. That way the C -compiler won't complain about unknown names. - - -<sect1>Header definition -<p><tscreen><verb> -HEADER <GEOS_TYPE> "dosname" "classname" "version" { - author "Joe Schmoe" - info "This is my killer-app!" - date yy mm dd hh ss - dostype SEQ - mode any - structure SEQ - icon "sprite.raw" -}</verb></tscreen> -The header definition describes the GEOS header sector which is unique to -each file. The definition starts with the keyword <tt/HEADER/, then goes the -GEOS file-type. You can use only <tt/APPLICATION/ here at the moment. Then, -there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS -Class name (up to 12 characters), and the version info (up to 4 characters). -The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the -major, and <em/y/ is the minor, version number. Those fields, along with both -braces, are required. The lines between braces are optional, and will be replaced -by default and current values. The keyword <tt/author/ and its value in quotes name -the programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can -have up to 95 characters. If the <tt/date/ field is omitted, then the time of -that compilation will be placed into the header. Note that, if you do specify -the date, you have to write all 5 numbers. The <tt/dostype/ can be <tt/SEQ/, -<tt/PRG/, or <tt/USR/. <tt/USR/ is used by default; GEOS usually doesn't care. -The <tt/mode/ can be <tt/any/, <tt/40only/, <tt/80only/, or <tt/c64only/; and, -it describes system requirements. <tt/any/ will work on both 64-GEOS and -128-GEOS, in 40- and 80-column modes. <tt/40only/ will work on 128-GEOS in -40-column mode only. <tt/80only/ will work on only 128-GEOS in 80-column mode, -and <tt/c64only/ will work on only 64-GEOS. The default value for -<tt/structure/ is <tt/SEQ/ (sequential). You can put <tt/VLIR/ there, too; but -then, you also have to put in a third type of resource -- a memory definition. -The value of <tt/icon/ is a quoted file-name. The first 63 bytes of this file -are expected to represent a standard monochrome VIC sprite. The file gets accessed -when the generated assembly source is being processed by <bf/ca65/. Examples for -programs generating such files are <em/Sprite Painter/, <em/SpritePad/ and the -<url name="sp65 sprite and bitmap utility" url="sp65.html">. The default <tt/icon/ -is an empty frame internally represented in the generated assembly file. - - -<sect1>Memory definition -<p><tscreen><verb> -MEMORY { - stacksize 0x0800 - overlaysize 0x2000 - overlaynums 0 1 2 4 5 -}</verb></tscreen> -The memory definition is unique to each file and describes several attributes related -to the memory layout. It consists of the keyword <tt/MEMORY/ followed by braces which -contain optional lines. The value of <tt/stacksize/ can be either decimal (e.g. -<tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/). The default value -of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be -either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied -background screen buffer while the latter means that the program uses the memory of the -background screen buffer for own purposes. The default value of <tt/yes/ comes from the -linker configuration file. If the <tt/structure/ in the header definition is set to the -value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the -VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number -0. It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. -<tt/0x1000/). <tt/overlaynums/ defines the VLIR record numbers used by the application. -Skipped numbers denote empty records. In the example, record number 3 is missing. Read -<ref name="this description" id="building-vlir"> for details. - - - -<sect>Building a GEOS sequential application<label id="building-seq"> -<p>Before proceeding, please read the <url name="compiler" url="cc65.html">, -<url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html"> -documentation, and find the appropriate sections about building programs, in -general. - -GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in -the GEOS world. It means that each file built with the cc65 package has to be -deconverted in GEOS, before it can be run. You can read a step-by-step -description of that in the <url name="GEOS section of the cc65 Compiler Intro" -url="intro-6.html#ss6.5">. - -Each project consists of four parts, two are provided by cc65. Those parts -are:<enum> -<item>application header -<item>start-up object -<item>application objects -<item>system library -</enum> -<bf/2./ and <bf/4./ come with cc65; however you have to write the application -yourself ;-) - -The application header is defined in the <tt/HEADER/ section of the <tt/.grc/ -file and is processed into an assembly <tt/.s/ file. You must assemble it, with -<bf/ca65/, into the object <tt/.o/ format. - -Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C -source), &dquot;<tt/test.h/&dquot; (a header file), and -&dquot;<tt/testres.grc/&dquot; (with menu and header definitions). Note the -fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot; -because you will have to be very careful with names (<bf/grc65/ will make -&dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of -&dquot;<tt/test.grc/&dquot; by default; and you don't want that because -&dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and -&dquot;<tt/test.h/&dquot; is something completely different)! - -<bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like: -<tscreen><verb> -#include <geos.h> -#include "testres.h" -</verb></tscreen> -There are no other includes. - - -<sect1>Building the GEOS application using cl65 -<p>This is a simple one step process: -<tscreen><verb> -cl65 -t geos-cbm -O -o test.cvt testres.grc test.c -</verb></tscreen> -Always place the <tt/.grc/ file as first input file on the command-line in order -to make sure that the generated <tt/.h/ file is available when it is needed for -inclusion by a <tt/.c/ file. - - -<sect1>Building the GEOS application without cl65 -<sect2>First step -- compiling the resources -<p> -<tscreen><verb> -grc65 -t geos-cbm testres.grc -</verb></tscreen> -will produce two output files: &dquot;<tt/testres.h/&dquot; and -&dquot;<tt/testres.s/&dquot;. - -Note that &dquot;<tt/testres.h/&dquot; is included at the top of -&dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step. - -<sect2>Second step -- assembling the application header -<p> -<tscreen><verb> -ca65 -t geos-cbm testres.s -</verb></tscreen> -And, voilá -- &dquot;<tt/testres.o/&dquot; is ready. - -<sect2>Third step -- compiling the code -<p> -<tscreen><verb> -cc65 -t geos-cbm -O test.c -ca65 -t geos-cbm test.s -</verb></tscreen> -That way, you have a &dquot;<tt/test.o/&dquot; object file which -contains all of the executable code. - -<sect2>Fourth and last step -- linking the application -<p> -<tscreen><verb> -ld65 -t geos-cbm -o test.cvt testres.o test.o geos-cbm.lib -</verb></tscreen> -The last file is the GEOS system library. - -The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's -contained in the well-known GEOS <em/Convert/ format. Note that its name -(<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name -that was given in the header definition. - -At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is -required for the correct process of GEOS sequential application building. - - - -<sect>Building a GEOS VLIR overlay application<label id="building-vlir"> -<p>Large GEOS applications typically don't fit in one piece in their designated -memory area. They are therefore split into overlays which are loaded into memory -on demand. The individual overlays are stored as records of a VLIR (Variable -Length Index Record) file. When GEOS starts a VLIR overlay appliation it loads -record number 0 which is supposed to contain the main program. The record numbers -starting with 1 are to be used for the actual overlays. - -In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting -of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/". - - -<sect1>Building the GEOS overlay application using cl65 -<p>This is a simple one step process: -<tscreen><verb> -cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c -</verb></tscreen> -Always place the <tt/.grc/ file as first input file on the command-line in order -to make sure that the generated <tt/.h/ file is available when it is needed for -inclusion by a <tt/.c/ file. - -You will almost certainly want to generate a map file that shows (beside a lot of -other infos) how large your individual overlays are. This info is necessary to tune -the distribution of code into the overlays and to optimize the memory area reserved -for the overlays. - - -<sect1>Building the GEOS overlay application without cl65 -<sect2>First step -- compiling the overlay resources -<p> -<tscreen><verb> -grc65 -t geos-cbm overlay-demores.grc -</verb></tscreen> - -<sect2>Second step -- assembling the overlay application header -<p> -<tscreen><verb> -ca65 -t geos-cbm overlay-demores.s -</verb></tscreen> - -<sect2>Third step -- compiling the overlay code -<p> -<tscreen><verb> -cc65 -t geos-cbm -O overlay-demo.c -ca65 -t geos-cbm overlay-demo.s -</verb></tscreen> - -<sect2>Fourth and last step -- linking the overlay application -<p> -<tscreen><verb> -ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos-cbm.lib -</verb></tscreen> - - - -<sect>Bugs and feedback -<p>This is the first release of <bf/grc65/, and it contains bugs, for sure! I -am aware of them; I know that the parser is weak, and if you don't follow the -grammar rules strictly, then everything will crash. However, if you find an -interesting bug, mail me. :-) Mail me also for help with writing your -<tt/.grc/ file correctly if you have problems with it. I would appreciate -comments also, and help on this file because I am sure that it can be written -better. - - - -<sect>Legal stuff -<p><bf/grc65/ is covered by the same license as the whole cc65 package, so you -should see its documentation for more info. Anyway, if you like it, and want -to encourage me to work more on it, send me a postcard with a sight of your -neighbourhood, city, region, etc. Or, just e-mail me with info that you -actually used it. See <url name="the GEOSLib documentation" url="geos.html"> -for addresses. - - - -<appendix> -<sect>Appendix A -- example.grc<label id="example-grc"> -<p><tscreen><verb> -; Note that MENU can define both menues and submenues. -; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT -; any spaces between the arguments (the parser is simple and weak). - -MENU subMenu1 15,0 VERTICAL -; This is a vertical menu, placed at (15,0). -{ -; There are three items, all of them will call functions. -; The first and third ones are normal functions, see GEOSLib documentation for -; information about what the second function should return (it's a dynamic one). - "subitem1" MENU_ACTION smenu1 - "subitem2" MENU_ACTION|DYN_SUB_MENU smenu2 - "subitem3" MENU_ACTION smenu3 -} - -;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... } - -MENU mainMenu 0,0 HORIZONTAL -; Here, we have our main menu, placed at (0,0), and it is a horizontal menu. -; Because it is a top-level menu, you would register it in your C source by -; using: DoMenu(&ero;mainMenu); -{ -; There are two items -- a submenu and an action. -; This calls a submenu named subMenu1 (see previous definition). - "first sub-menu" SUB_MENU subMenu1 -; This will work the same as an EnterDeskTop() call in C source code. - "quit" MENU_ACTION EnterDeskTop -} - -;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version" - -HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0" -; This is a header for an APPLICATION which will be seen in the directory as a -; file named MyFirstApp with the Class-string "Class Name V1.0" -{ -; Not all fields are required, default and current values will be used. - author "Maciej Witkowiak" ; always in quotes! - info "Information text" ; always in quotes! -; date yy mm dd hh ss ; always 5 fields! -; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case) -; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case) - mode c64only ; can be: any, 40only, 80only, c64only -}</verb></tscreen> -</article> diff --git a/doc/index.sgml b/doc/index.sgml deleted file mode 100644 index e0b110ead..000000000 --- a/doc/index.sgml +++ /dev/null @@ -1,179 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>cc65 Documentation Overview -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2005-8-6 - -<abstract> -Main documentation page, contains links to other available stuff. -</abstract> - -<sect>Program documentation<p> - -<descrip> - - <tag><htmlurl url="ar65.html" name="ar65.html"></tag> - Describes the ar65 archiver. - - <tag><htmlurl url="ca65.html" name="ca65.html"></tag> - Describes the ca65 macro assembler. - - <tag><htmlurl url="ca65html.html" name="ca65html.html"></tag> - Describes the ca65html assembler-source-to-HTML converter. - - <tag><htmlurl url="cc65.html" name="cc65.html"></tag> - Describes the cc65 C compiler. - - <tag><htmlurl url="cl65.html" name="cl65.html"></tag> - Describes the cl65 compile & link utility. - - <tag><htmlurl url="co65.html" name="co65.html"></tag> - Describes the co65 object-file converter. - - <tag><htmlurl url="da65.html" name="da65.html"></tag> - Describes the da65 6502/65C02 disassembler. - - <tag><htmlurl url="grc65.html" name="grc65.html"></tag> - Describes the GEOS resource compiler (grc65). - - <tag><htmlurl url="ld65.html" name="ld65.html"></tag> - Describes the ld65 linker. - - <tag><htmlurl url="od65.html" name="od65.html"></tag> - Describes the od65 object-file analyzer. - - <tag><htmlurl url="sp65.html" name="sp65.html"></tag> - Describes the sprite and bitmap utility. - -</descrip> - - -<sect>Usage<p> - -<descrip> - - <tag><htmlurl url="intro.html" name="intro.html"></tag> - Describes the use of the tools, by building a short &dquot;hello world&dquot; - example. - - <tag><htmlurl url="coding.html" name="coding.html"></tag> - Contains hints on creating the most effective code with cc65. - - <tag><htmlurl url="compile.txt" name="compile.txt"></tag> - How to compile cc65 and the support tools. - - <tag><htmlurl url="using-make.html" name="using-make.html"></tag> - Build programs, using the GNU Make utility. - - <tag><htmlurl url="customizing.html" name="customizing.html"></tag> - How to use the cc65 toolset for a custom hardware platform (a target system - not currently supported by the cc65 library set). - - <tag><htmlurl url="debugging.html" name="debugging.html"></tag> - Debug programs, using the VICE emulator. - -</descrip> - - -<sect>Library information and other references<p> - -<descrip> - - <tag><htmlurl url="funcref.html" name="funcref.html"></tag> - A (currently incomplete) function reference. - - <tag><htmlurl url="dio.html" name="dio.html"></tag> - Low-level disk I/O API. - - <tag><htmlurl url="geos.html" name="geos.html"></tag> - The GEOSLib manual. - - <tag><htmlurl url="internal.txt" name="internal.txt"></tag> - A somewhat older text describing several cc65 internals. - - <tag><htmlurl url="library.html" name="library.html"></tag> - An overview over the cc65 runtime and C libraries. - - <tag><htmlurl url="smc.html" name="smc.html"></tag> - Describes Christian Krügers macro package for writing self modifying - assembler code. - - <tag><url name="6502 Binary Relocation Format document" - url="http://www.6502.org/users/andre/o65/fileformat.html"></tag> - Describes the o65 file format that is used for dynamically loadable modules - and LUnix programs. - -</descrip> - - -<sect>Platform-specific information<p> - -<descrip> - - <tag><htmlurl url="apple2.html" name="apple2.html"></tag> - Topics specific to the Apple ][. - - <tag><htmlurl url="apple2enh.html" name="apple2enh.html"></tag> - Topics specific to the enhanced Apple //e. - - <tag><htmlurl url="atari.html" name="atari.html"></tag> - Topics specific to the Atari 8-bit machines. - - <tag><htmlurl url="atmos.html" name="atmos.html"></tag> - Topics specific to the Oric Atmos. - - <tag><htmlurl url="c128.html" name="c128.html"></tag> - Topics specific to the Commodore 128. - - <tag><htmlurl url="c16.html" name="c16.html"></tag> - Topics specific to the Commodore 16/116. - - <tag><htmlurl url="c64.html" name="c64.html"></tag> - Topics specific to the Commodore 64. - - <tag><htmlurl url="cbm510.html" name="cbm510.html"></tag> - Topics specific to the Commodore 510. - - <tag><htmlurl url="cbm610.html" name="cbm610.html"></tag> - Topics specific to the Commodore 610. - - <tag><htmlurl url="lynx.html" name="lynx.html"></tag> - Topics specific to the Atari Lynx Game Console. - - <tag><htmlurl url="nes.html" name="nes.html"></tag> - Topics specific to the Nintendo Entertainment System. - - <tag><htmlurl url="pet.html" name="pet.html"></tag> - Topics specific to the Commodore PET machines. - - <tag><htmlurl url="plus4.html" name="plus4.html"></tag> - Topics specific to the Commodore Plus/4. - - <tag><htmlurl url="supervision.html" name="supervision.html"></tag> - Topics specific to the Supervision Console. - - <tag><htmlurl url="vic20.html" name="vic20.html"></tag> - Topics specific to the Commodore VIC20. - -</descrip> - - -<sect>Miscellaneous<p> - -<descrip> - - <tag><htmlurl url="newvers.txt" name="newvers.txt"></tag> - Somewhat outdated. Lists the differences between my cc65 releases - and the original Atari version that was created by J. R. Dunning. - - <tag><htmlurl url="BUGS" name="BUGS"></tag> - Known cc65 bugs. - - <tag><htmlurl url="CREDITS" name="CREDITS"></tag> - Here is who helped with the compiler and other tools. - -</descrip> - -</article> - diff --git a/doc/internal.txt b/doc/internal.txt deleted file mode 100644 index 0dca618ea..000000000 --- a/doc/internal.txt +++ /dev/null @@ -1,207 +0,0 @@ - - - Internals doc for CC65 - - - -Stacks: -------- - -The program stack used by programs compiled with CC65 is located in high -memory. The stack starts there and grows down. Arguments to functions, local -data etc are allocated on this stack, and deallocated when functions exit. - -The program code and data is located in low memory. The heap is located -between the program code and the stack. The default size for the parameter -stack is 2K, you may change this for most platforms in the linker -configuration. - -Note: The size of the stack is only needed if you use the heap, or if you -call the stack checking routine (_stkcheck) from somewhere in your program. - -When calling other functions, the return address goes on the normal 6502 -stack, *not* on the parameter stack. - - - -Registers: ----------- - -Since CC65 is a member of the Small-C family of compilers, it uses the notion -of a 'primary register'. In the CC65 implementation, I used the AX register -pair as the primary register. Just about everything interesting that the -library code does is done by somehow getting a value into AX, and then calling -some routine or other. In places where Small-C would use a secondary -register, top-of-stack is used, so for instance two argument function like -integer-multiply work by loading AX, pushing it on the stack, loading the -second value, and calling the internal function. The stack is popped, and the -result comes back in AX. - - - -Calling sequences: ------------------- - -C functions are called by pushing their args on the stack, and JSR'ing to the -entry point. (See ex 1, below) If the function returns a value, it comes back -in AX. NOTE!!! A potentially significant difference between the CC65 -environment and other C environments is that the CALLEE pops arguments, not -the CALLER. (This is done so as to generate more compact code) In normal use, -this doesn't cause any problems, as the normal function entry/exit conventions -take care of popping the right number of things off the stack, but you may -have to worry about it when doing things like writing hand-coded assembly -language routines that take variable numbers of arguments. More about that -later. - -Ex 1: Function call: Assuming 'i' declared int and 'c' declared - char, the following C code - - i = baz(i, c); - - in absence of a prototype generates this assembler code. I've added - the comments. - - lda _i ; get 'i', low byte - ldx _i+1 ; get 'i', hi byte - jsr pushax ; push it - lda _c ; get 'c' - ldx #0 ; fill hi byte with 0 - jsr pushax ; push it - ldy #4 ; arg size - jsr _baz ; call the function - sta _i ; store the result - stx _i+1 - - In presence of a prototype, the picture changes slightly, since the - compiler is able to do some optimizations: - - lda _i ; get 'i', low byte - ldx _i+1 ; get 'i', hi byte - jsr pushax ; push it - lda _c ; get 'c' - jsr pusha ; push it - jsr _baz ; call the function - sta _i ; store the result - stx _i+1 - - -Note that the two words of arguments to baz were popped before it exitted. -The way baz could tell how much to pop was by the argument count in Y at call -time. Thus, even if baz had been called with 3 args instead of the 2 it was -expecting, that would not cause stack corruption. - -There's another tricky part about all this, though. Note that the args to baz -are pushed in FORWARD order, ie the order they appear in the C statement. -That means that if you call a function with a different number of args than it -was expecting, they wont end up in the right places, ie if you call baz, as -above, with 3 args, it'll operate on the LAST two, not the first two. - - - -Symbols: --------- - -CC65 does the usual trick of prepending an underbar ('_') to symbol names when -compiling them into assembler. Therefore if you have a C function named -'bar', CC65 will define and refer to it as '_bar'. - - - -Systems: --------- - -Supported systems at this time are: C64, C128, Plus/4, CBM 500, CBM 600/700, -the newer PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to -Kevin Ruland, who did the port). - -C16: Works with unexpanded or memory expanded C16 and C116 machines. - However, a maximum of 32KB from the total memory is used. The Plus/4 - target supports up to 64K of memory, but has a small code overhead - because of the banking routines involved. Apart from this additional - overhead, the Plus/4 target and the C16 target are the same. 16K - machines (unexpanded C16) have 12K of memory for C programs available, - machines with 32K or more have 28K available. The actual amount of - memory is auto detected. - -C64: The program runs in a memory configuration, where only the kernal ROM - is enabled. The text screen is expected at the usual place ($400), so - 50K of memory are available to the program. - -C128: The startup code will reprogram the MMU, so that only the kernal ROM - is enabled. This means, there are 41K of memory available to the - program. - -Plus/4: Works with bank switching so 59K of memory are available to the - program. - -CBM 500: - The C program runs in bank #0 and has a total of 48K memory available. - This is less than what is available on its bigger brothers (CBM - 600/700) because the character data and video RAM is placed in the - execution bank (#0) to allow the use of sprites. - -CBM 600/700: - The C program runs in a separate segment and has almost full 64K of - memory available. - -PET: The startup code will adjust the upper memory limit to the installed - memory. However, only linear memory is used, this limits the top to - $8000, so on a 8032 or similar machine, 31K of memory are available to - the program. - -Apple ][: - The program starts at $803, end of RAM is $95FF, so 35.5K of memory - (including stack) are available to the program. - -Atari: The startup code will adjust the upper memory limit to the installed - memory detected at runtime. The programmer can adjust the upper memory - limit by setting the __RESERVED_MEMORY__ variable at link time. The - given __RESERVED_MEMORY__ value will be subtracted from the upper - memory limit used by the runtine. This memory could be used as graphics - memory, for example. - In the default case (no setting of __RESERVED_MEMORY__) the upper - memory limit is $9C1F (with Basic cartridge) and $BC1F (without - cartridge). The program starts at $2E00 by default. - These values are for a 48K or 64K machine. - -Note: The above numbers do not mean that the remaining memory is unusable. -However, it is not linear memory and must be accessed by other, nonportable -methods. I'm thinking about a library extension that allows access to the -additional memory as a far heap, but these routines do not exist until now. - - - -Inline Assembly: ----------------- - -CC65 allows inline assembly by a special keyword named "asm". Inline assembly -looks like a function call. The string in parenthesis is output in the -assembler file. - -Example, insert a break instruction into the code: - - asm ("brk") - -Beware: Be careful when inserting inline code since this may collide with -the work of the optimizer. - - - -Pseudo variables: ------------------ - -There are two special variables available named __AX__ and __EAX__. These -variables must never be declared (this gives an error), but may be used as any -other variable. However, accessing these variables will access the primary -register that is used by the compiler to evaluate expressions, return -functions results and pass parameters. - -This feature is useful with inline assembly and macros. For example, a macro -that reads a CRTC register may be written like this: - -#define wr(idx) (__AX__=(idx), \ - asm ("sta $2000"), \ - asm ("lda $2000"), \ - asm ("ldx #$00"), \ - __AX__) - diff --git a/doc/intro.sgml b/doc/intro.sgml deleted file mode 100644 index c5ef7956a..000000000 --- a/doc/intro.sgml +++ /dev/null @@ -1,527 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>cc65 Compiler Intro -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">, -<and>CbmNut, <htmlurl url="mailto:cbmnut@hushmail.com" name="cbmnut@hushmail.com">, -<and><url name="Greg King" url="mailto:gngking@erols.com"> -<date>2005-7-22 - -<abstract> -How to use the cc65 C language system -- an introduction. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This is a short intro of how to use the compiler and the bin-utils. It contains -a step-by-step example of how to build a complete application from one C and -one assembly modules. This file does <em/not/ contain a complete reference for -the tools used in the process. There are separate files describing those tools, -in detail (see <url url="index.html">). - -I do assume that you have downloaded and installed the compiler and -target-specific files. Windows users should use the friendly .exe installer -(named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the -version number if necessary). It does not only install the target files, but -will also set up necessary environment variables for you. - -If you're going for the .ZIP archives, please note that there is one file for -the host platform (Windows, DOS or OS/2), one file for each target platform -(C64 or whatever) and a separate file containing the docs (which include the -file you're currently reading). So for most uses, you will need at least 3 -files and unpack all three into one directory. In case of the .ZIP archives, -you will also need to set the environment variables <tt/CC65_INC/, -<tt/LD65_LIB/ and <tt/LD65_CFG/ as described below. - -<bf/Note/: There is a much simpler way to compile this example, by using the -<bf/cl65/ compile-and-link utility. However, it makes sense to understand how -the separate steps work. How to do the example with the <bf/cl65/ utility is -described <ref id="using-cl65" name="later">. - - -<sect1>Before we start<p> - -You will find a copy of the sample modules, used in the next section, in the -"<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with -missing include files and/or libraries, please check the environment variables -<tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the -<tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you -installed cc65. - - -<sect1>The sample modules<p> - -To explain the development flow, I will use the following example modules: - -hello.c: -<tscreen><code> - #include <stdio.h> - #include <stdlib.h> - - extern const char text[]; /* In text.s */ - - int main (void) - { - printf ("%s\n", text); - return EXIT_SUCCESS; - } -</code></tscreen> - -text.s: -<tscreen><code> - .export _text - _text: .asciiz "Hello world!" -</code></tscreen> - - -<sect1>Translation phases<p> - -We assume that the target file should be named "hello", and the target system -is the C64. - -<tscreen><verb> - +---------+ - | hello.c | - +---------+ - | - cc65 - \/ - +---------+ +---------+ +---------+ - | hello.s | | text.s | | crt0.o | - +---------+ +---------+ +---------+ - | | | - ca65 ca65 ar65 - \/ \/ \/ - +---------+ +---------+ +---------+ - | hello.o | | text.o | | c64.lib | - +---------+ +---------+ +---------+ - | \ / - | \ / - | \ / - +----------------------->ld65< - \/ - hello -</verb></tscreen> - -<tt/crt0.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime -and C library) are provided in binary form in the cc65 package. Actually, the -startup code is contained in the library, so you won't need to care about it. - - - -<sect>The compiler<p> - -The compiler translates one C source into one assembly source, for each -invocation. It does <em/not/ create object files directly, and it is <em/not/ -able to translate more than one file per run. - -In the example above, we would use the following command line, to translate -<tt/hello.c/ into <tt/hello.s/: - -<tscreen><verb> - cc65 -O -t c64 hello.c -</verb></tscreen> - -The <tt/-O/ switch tells the compiler to do an additional optimizer run, which -is usually a good idea, since it makes the code smaller. If you don't care -about the size, but want to have slightly faster code, use <tt/-Oi/ to inline -some runtime functions. - -The <tt/-t/ switch is followed by the target system name. - -If the compiler does not complain about errors in our "hello world" program, we -will have a file named "<tt/hello.s/", in our directory, that contains the -assembly source for the <bf/hello/ module. - -For more information about the compiler, see <url url="cc65.html">. - - - -<sect>The assembler<p> - -The assembler translates one assembly source into an object file, for each -invocation. The assembler is <em/not/ able to translate more than one source -file per run. - -Let's translate the "hello.s" and "text.s" files from our example: - -<tscreen><verb> - ca65 hello.s - ca65 -t c64 text.s -</verb></tscreen> - -The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the -text is converted from the input character-set (usually ISO-8859-1) into the -target character-set (PETSCII, in this example) by the assembler. The -compiler-generated file <tt/hello.s/ does not contain any character constants, -so specification of a target is not necessary (it wouldn't do any harm, -however). - -If the assembler does not complain, we should now have two object files (named -<tt/hello.o/ and <tt/text.o/) in the current directory. - -For more information about the assembler, see <url url="ca65.html">. - - - -<sect>The linker<p> - -The linker combines several object and library files into one output file. -<bf/ld65/ is very configurable, but fortunately has built-in configurations, -so we don't need to mess with configuration files, here. - -The compiler uses small functions to do things that cannot be done inline -without a big impact on code size. Those runtime functions, together with the -C library, are in an object-file archive named after the system, in this case, -"<tt/c64.lib/". We have to specify that file on the command line, so that the -linker can resolve those functions. - -Let's link our files to get the final executable: - -<tscreen><verb> - ld65 -o hello -t c64 hello.o text.o c64.lib -</verb></tscreen> - -The argument after <tt/-o/ specifies the name of the output file, the argument -after <tt/-t/ gives the target system. The following arguments are object -files or libraries. Since the target library resolves imports in <tt/hello.o/ -and <tt/text.o/, it must be specified <em/after/ those files. - -After a successful linker run, we have a file named "<tt/hello/", ready for -our C64! - -For more information about the linker, see <url url="ld65.html">. - - - -<sect>The easy way (using the cl65 utility)<label id="using-cl65"><p> - -The <bf/cl65/ utility is able to do all of the steps described above, in just -one command line, and it has defaults for some options that are very -well-suited for our example. - -To compile both files into one executable, enter: - -<tscreen><verb> - cl65 -O hello.c text.s -</verb></tscreen> - -The <bf/cl65/ utility knows how to translate C files into object files (it will -call the compiler, and then the assembler). It does know also how to create -object files from assembly files (it will call only the assembler, for that). -It knows how to build an executable (it will pass all object files to the -linker). And finally, it has the C64 as a default target, and will supply the -correct startup file and runtime library names to the linker, so you don't -have to care about that. - -The one-liner above should give you a C64 executable named "<tt/hello/" in the -current directory. - -For more information about the compile & link utility, see <url -url="cl65.html">. - - - -<sect>Running The Executable<p> - -<em/Note: this section is incomplete!/ - -Depending on the target, cc65 chooses several methods of making a program -available for execution. Here, we list sample emulators and instructions for -running the program. Unless noted, similar instructions would also apply to a -real machine. One word of advice: we suggest you clear the screen at the -start, and wait for a keypress at the end of your program, as each target -varies in its start and exit conditions. - - -<sect1>Apple - -<sect2>AppleWin<p> -Available at <url -url="http://applewin.berlios.de/">: - -Emulates Apple ][/enhanced Apple //e computers, with -sound, video, joysticks, serial port, and disk images. Includes monitor. Only -for Windows. The package comes with a DOS 3.3 disk (called "master.dsk") image; -however, you will need <bf/AppleCommander 1.3.5/ or later (available at <url -url="http://applecommander.sourceforge.net/">). - -Compile the tutorial with - -<tscreen><verb> -cl65 -O -t apple2 hello.c text.s -</verb></tscreen> -for the Apple ][, or: -<tscreen><verb> -cl65 -O -t apple2enh hello.c text.s -</verb></tscreen> -for the enhanced Apple //e. - -Then, put the file onto an Apple disk image, for use with an emulator. Copy -the <tt/master.dsk/ which comes with <bf/AppleWin/, and rename it to -<tt/cc65.dsk/, then use <bf/AppleCommander/: - -<tscreen><verb> -java -jar ac.jar -cc65 cc65.dsk test B < hello -</verb></tscreen> - -Note that a convention in the Apple world is that "hello" is the file which is -run automatically upon booting a DOS disk, sort of like the "autoexec.bat" of -the MSDOS/Windows world. We've avoided that in the example, however. Also, -the <tt/B/ parameter must be in caps., and "test" is the name of the program as -it will appear on the Apple disk. - -Start the emulator, click on the <bf/Disk 1/ icon, and point to <bf/cc65.dsk/; -then, click the big Apple logo, to boot the system. Then, type this on the -Apple: - -<tscreen><verb> -BRUN TEST -</verb></tscreen> - -You will see the "Hello, World!" appear on the same line. Thanks to Oliver -Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> for his help -in completing this section. - - -<sect1>Atari - -<sect2>Atari800Win PLus<p> -Available at <url -url="http://www.atari.org.pl/PLus/index_us.htm">: - -Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk -images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM -expansions. Includes monitor. Unfortunately, only for Windows. You will need -the emulator, "atarixl.rom" or "atariosb.rom"/"ataribas.rom", and "dos25.xfd" -files (not supplied). - -Compile the tutorial with - -<tscreen><verb> -cl65 -O -t atari hello.c text.s -</verb></tscreen> - -Start the emulator, choose <bf/File>Autoboot image/ or <bf/File>Load -executable/, and point to the "<bf/hello/" executable. It is customary to -rename executables of that type to "<bf/hello.xex/". The file has a 7-byte -header meant to be loaded directly from Atari DOS 2/2.5 or compatibles. - -On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible. -Turn on the computer, type - -<tscreen><verb> -DOS -</verb></tscreen> - -at the BASIC prompt, then choose <bf/N. CREATE MEM.SAV/, -then choose <bf/L. BINARY LOAD/, and enter <tt/HELLO/. - -The emulation, also, supports that method. Look at <bf/Atari>Settings/, and -check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari>Hard -disks/, and set the path of <bf/H1:/ to your executables directory, then use -"<bf/H0:HELLO.XEX/" in the above procedure (after pressing <tt/L/), to access -your harddrive directly. - -<bf/Note/: There is no delay after the program exits, as you are returned -to the DOS menu. Your C program should wait for a keypress if you want to see -any output. - - -<sect1>Atmos - -<sect2>Oricutron<p> -Available at <url -url="http://code.google.com/p/oriculator/">: - -Emulates Oric-1 and Atmos computers, with sound, disk images, -scanline-exact NTSC/PAL video, and movie export. Includes monitor. -Fortunately for all SDL platforms. You will just need the emulator, all -ROMs are supplied. - -Compile the tutorial with - -<tscreen><verb> -cl65 -O -t atmos hello.c text.s -o hello.tap -</verb></tscreen> - -Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to -the "<bf/hello.tap/" executable. The file has an auto start header meant to -be loaded directly from tape. - -On a real Atmos, you would need a tape drive. -Turn on the computer, type - -<tscreen><verb> -CLOAD"" -</verb></tscreen> - -at the BASIC prompt. - -The emulation, also, supports that method. - - -<sect1>Commodore - -<sect2>VICE<p> -Available at <url -url="http://www.viceteam.org/">: - -Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports -printers, serial port and adapters, stereo sound, disk drives and images, RAM -expansions, cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, -and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2, -BeOS x86, Acorn RISC OS, and most Unixes. - -Compile the tutorial with -<tscreen><verb> -cl65 -O -t <sys> hello.c text.s -</verb></tscreen> -Substitute the name of a Commodore computer for that <tt/<sys>/: -<itemize> -<item><tt/c128/ -<item><tt/c16/ -<item><tt/c64/ -<item><tt/cbm510/ -<item><tt/cbm610/ -<item><tt/pet/ -<item><tt/plus4/ -<item><tt/vic20/ -</itemize> - -Start the desired version of the emulator (CBM510 and CBM610 programs run on -the CBM II [<tt/xcbm2/] emulator). - -In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape -image...</bf>, choose your executable, and click <bf/OK/. - -In the Unix versions, hold down the mouse's first button. Move the pointer to -<bf>Smart-attach disk/tape...</bf>, and release the button. Choose your -executable, and click <bf/Autostart/. - -The file has a 14-byte header which corresponds to a PRG-format BASIC program, -consisting of a single line, similar to this: - -<tscreen><code> -1000 sys2061 -</code></tscreen> - -On a real Commodore with attached disk drive, you would type: - -<tscreen><verb> -LOAD "0:HELLO",8 -</verb></tscreen> - -for VIC-20/C64, or: - -<tscreen><verb> -DLOAD "HELLO" -</verb></tscreen> - -on PET/CBM II/C128/C16/Plus 4; then, type - -<tscreen><verb> -RUN -</verb></tscreen> - -On a Commodore 128, you can combine those two commands: -<tscreen><verb> -RUN "HELLO" -</verb></tscreen> - -The output will appear on a separate line, and you will be returned to a BASIC -prompt. - - -<sect1>GEOS<p> -Available at <it/Click Here Software's/ <url -url="http://cbmfiles.com/geos/index.html" name="GEOS download section">: - -<it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it> -It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User -Interface) for Commodore's computer models <bf/64/ and <bf/128/. It can be -controlled by many different types of input devices: -<itemize> -<item>keyboard -<item>joysticks -<item>mice -<item>trackballs -<item>graphics drawing tablets -<item>light-pens -</itemize> - -The tutorial files are different for GEOS. You will find them "next door," in -"<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and -"<tt/hello1res.grc/". - -Compile the tutorial with -<tscreen><verb> -cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c -</verb></tscreen> -Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk. - -Boot the GEOS master disk/image. - -<quote> -When you want to run GEOS in an emulator, you must adjust that emulator so that -it does a "true drive" emulation. Each emulator has its own way of turning that -feature on. -</quote> - -<quote> -VICE even has different ways that depend on which operating system is running -the emulator. -<itemize> -<item>In Windows, you must click on <bf/Options/ (in an always visible menu). - Then, you must click on <bf/True drive emulation/. -<item>In Unix, you must <em/hold down/ the second button on your mouse. Move - the pointer down to <bf/Drive settings/. Then, move the pointer over to - <bf/Enable true drive emulation/. (If there is a check-mark in front of - those words, that feature already is turned on -- then, move the pointer - off of that menu.) Release the mouse button. -</itemize> -</quote> - -Find the <bf/CONVERT/ program on the boot disk [tap the 6-key; then, you -should see its icon in the fourth position on the <bf/deskTop/'s directory -notePad]. Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click -it to run that program. Click on the <bf/Disk/ icon; put the disk with -"<tt/hello1/" into the drive; and, click the <bf/OK/ icon. Use the little -icons under the list of file-names to move through that list until you find -"<tt/hello1/". Click on it; and then, click on the <bf/Convrt/ icon. -<bf/CONVERT/ will ask you to confirm that you choose the correct file; click -<bf/YES/ if you did (or, click <bf/NO/ if you made a mistake). After the -program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will -announce what it did -- click on <bf/OK/. <bf/CONVERT/ will show the file list -again. This time, click on <bf/Quit/. - -(You might need to put the boot disk back into the drive, in order to reload -<bf/deskTop/. Then, you must swap back to the disk with the tutorial program -on it, and click on its disk icon [on the right side of the screen].) - -Now, you must find <bf/hello1/. Click on the lower left-hand corner of the -directory notePad. Look at the eight file-positions on each page until you see -<bf/hello1/. Double-click on its icon. - -The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished -reading it. - - -<sect1>Contributions wanted<p> - -We need your help! Recommended emulators and instructions for other targets -are missing. We suggest that you choose emulators with good compatibility. -Also, being able to run all computers in the target series is good for -target compatibility testing. A machine-language monitor is almost essential -for debugging, but a native debugger could be used, as well. - -Finally, emulators which run on Unix or Windows would help to reach a wider -audience. - -</article> diff --git a/doc/ld65.sgml b/doc/ld65.sgml deleted file mode 100644 index 5330a21d9..000000000 --- a/doc/ld65.sgml +++ /dev/null @@ -1,1114 +0,0 @@ -<!doctype linuxdoc system> <!-- -*- text-mode -*- --> - -<article> -<title>ld65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>02.12.2000, 02.10.2001 - -<abstract> -The ld65 linker combines object files into an executable file. ld65 is highly -configurable and uses configuration files for high flexibility. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -The ld65 linker combines several object modules created by the ca65 -assembler, producing an executable file. The object modules may be read -from a library created by the ar65 archiver (this is somewhat faster and -more convenient). The linker was designed to be as flexible as possible. -It complements the features that are built into the ca65 macroassembler: - -<itemize> - -<item> Accept any number of segments to form an executable module. - -<item> Resolve arbitrary expressions stored in the object files. - -<item> In case of errors, use the meta information stored in the object files - to produce helpful error messages. In case of undefined symbols, - expression range errors, or symbol type mismatches, ld65 is able to - tell you the exact location in the original assembler source, where - the symbol was referenced. - -<item> Flexible output. The output of ld65 is highly configurable by a config - file. More common platforms are supported by builtin configurations - that may be activated by naming the target system. The output - generation was designed with different output formats in mind, so - adding other formats shouldn't be a great problem. - -</itemize> - - -<sect>Usage<p> - - -<sect1>Command line option overview<p> - -The linker is called as follows: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: ld65 [options] module ... -Short options: - -( Start a library group - -) End a library group - -C name Use linker config file - -D sym=val Define a symbol - -L path Specify a library search path - -Ln name Create a VICE label file - -S addr Set the default start address - -V Print the linker version - -h Help (this text) - -m name Create a map file - -o name Name the default output file - -t sys Set the target system - -u sym Force an import of symbol `sym' - -v Verbose mode - -vm Verbose map file - -Long options: - --cfg-path path Specify a config file search path - --config name Use linker config file - --dbgfile name Generate debug information - --define sym=val Define a symbol - --dump-config name Dump a builtin configuration - --end-group End a library group - --force-import sym Force an import of symbol `sym' - --help Help (this text) - --lib file Link this library - --lib-path path Specify a library search path - --mapfile name Create a map file - --module-id id Specify a module id - --obj file Link this object file - --obj-path path Specify an object file search path - --start-addr addr Set the default start address - --start-group Start a library group - --target sys Set the target system - --version Print the linker version ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<p> - -Here is a description of all the command line options: - -<descrip> - - <label id="option--start-group"> - <tag><tt>-(, --start-group</tt></tag> - - Start a library group. The libraries specified within a group are searched - multiple times to resolve crossreferences within the libraries. Normally, - crossreferences are only resolved within a library, that is the library is - searched multiple times. Libraries specified later on the command line - cannot reference otherwise unreferenced symbols in libraries specified - earlier, because the linker has already handled them. Library groups are - a solution for this problem, because the linker will search repeatedly - through all libraries specified in the group, until all possible open - symbol references have been satisfied. - - - <tag><tt>-), --end-group</tt></tag> - - End a library group. See the explanation of the <tt><ref - id="option--start-group" name="--start-group"></tt> option. - - - <tag><tt>-h, --help</tt></tag> - - Print the short option summary shown above. - - - <label id="option-m"> - <tag><tt>-m name, --mapfile name</tt></tag> - - This option (which needs an argument that will used as a filename for - the generated map file) will cause the linker to generate a map file. - The map file does contain a detailed overview over the modules used, the - sizes for the different segments, and a table containing exported - symbols. - - - <label id="option-o"> - <tag><tt>-o name</tt></tag> - - The -o switch is used to give the name of the default output file. - Depending on your output configuration, this name may NOT be used as - name for the output file. However, for the builtin configurations, this - name is used for the output file name. - - - <label id="option-t"> - <tag><tt>-t sys, --target sys</tt></tag> - - The argument for the -t switch is the name of the target system. Since this - switch will activate a builtin configuration, it may not be used together - with the <tt><ref id="option-C" name="-C"></tt> option. The following target - systems are currently supported: - - <itemize> - <item>none - <item>module - <item>apple2 - <item>apple2enh - <item>atari - <item>atmos - <item>c16 (works also for the c116 with memory up to 32K) - <item>c64 - <item>c128 - <item>cbm510 (CBM-II series with 40 column video) - <item>cbm610 (all CBM series-II computers with 80 column video) - <item>geos-apple - <item>geos-cbm - <item>lunix - <item>lynx - <item>nes - <item>pet (all CBM PET systems except the 2001) - <item>plus4 - <item>supervision - <item>vic20 - </itemize> - - There are a few more targets defined but neither of them is actually - supported. - - - <tag><tt>-u sym[:addrsize], --force-import sym[:addrsize]</tt></tag> - - Force an import of a symbol. While object files are always linked to the - output file, regardless if there are any references, object modules from - libraries get only linked in if an import can be satisfied by this module. - The <tt/--fore-import/ option may be used to add a reference to a symbol and - as a result force linkage of the module that exports the identifier. - - The name of the symbol may optionally be followed by a colon and an address - size specifier. If no address size is specified, the default address size - for the target machine is used. - - Please note that the symbol name needs to have the internal representation, - meaning you have to prepend an underline for C identifiers. - - - <label id="option-v"> - <tag><tt>-v, --verbose</tt></tag> - - Using the -v option, you may enable more output that may help you to - locate problems. If an undefined symbol is encountered, -v causes the - linker to print a detailed list of the references (that is, source file - and line) for this symbol. - - - <tag><tt>-vm</tt></tag> - - Must be used in conjunction with <tt><ref id="option-m" name="-m"></tt> - (generate map file). Normally the map file will not include empty segments - and sections, or unreferenced symbols. Using this option, you can force the - linker to include all this information into the map file. - - - <label id="option-C"> - <tag><tt>-C</tt></tag> - - This gives the name of an output config file to use. See section 4 for more - information about config files. -C may not be used together with <tt><ref - id="option-t" name="-t"></tt>. - - - <label id="option-D"> - <tag><tt>-D sym=value, --define sym=value</tt></tag> - - This option allows to define an external symbol on the command line. Value - may start with a '$' sign or with <tt/0x/ for hexadecimal values, - otherwise a leading zero denotes octal values. See also the <ref - id="SYMBOLS" name="SYMBOLS section"> in the configuration file. - - - <label id="option--lib-path"> - <tag><tt>-L path, --lib-path path</tt></tag> - - Specify a library search path. This option may be used more than once. It - adds a directory to the search path for library files. Libraries specified - without a path are searched in current directory, in the directory given in - the <tt/LD65_LIB/ environment variable, and in the list of directories - specified using <tt/--lib-path/. - - - <tag><tt>-Ln</tt></tag> - - This option allows you to create a file that contains all global labels and - may be loaded into VICE emulator using the <tt/ll/ (load label) command. You - may use this to debug your code with VICE. Note: Older versions had some - bugs in the label code. If you have problems, please get the latest VICE - version. - - - <label id="option-S"> - <tag><tt>-S addr, --start-addr addr</tt></tag> - - Using -S you may define the default starting address. If and how this - address is used depends on the config file in use. For the builtin - configurations, only the "none", "apple2" and "apple2enh" systems honor an - explicit start address, all other builtin config provide their own. - - - <tag><tt>-V, --version</tt></tag> - - This option print the version number of the linker. If you send any - suggestions or bugfixes, please include this number. - - - <label id="option--cfg-path"> - <tag><tt>--cfg-path path</tt></tag> - - Specify a config file search path. This option may be used more than once. - It adds a directory to the search path for config files. A config file given - with the <tt><ref id="option-C" name="-C"></tt> option that has no path in - its name is searched in the current directory, in the directory given in the - <tt/LD65_CFG/ environment variable, and in the list of directories specified - using <tt/--cfg-path/. - - - <label id="option--dbgfile"> - <tag><tt>--dbgfile name</tt></tag> - - Specify an output file for debug information. Available information will be - written to this file. Using the <tt/-g/ option for the compiler and assembler - will increase the amount of information available. Please note that debug - information generation is currently being developed, so the format of the - file and its contents are subject to change without further notice. - - - <tag><tt>--lib file</tt></tag> - - Links a library to the output. Use this command line option instead of just - naming the library file, if the linker is not able to determine the file - type because of an unusual extension. - - - <tag><tt>--obj file</tt></tag> - - Links an object file to the output. Use this command line option instead - of just naming the object file, if the linker is not able to determine the - file type because of an unusual extension. - - - <label id="option--obj-path"> - <tag><tt>--obj-path path</tt></tag> - - Specify an object file search path. This option may be used more than once. - It adds a directory to the search path for object files. An object file - passed to the linker that has no path in its name is searched in current - directory, in the directory given in the <tt/LD65_OBJ/ environment variable, - and in the list of directories specified using <tt/--obj-path/. - -</descrip> - - - -<sect>Search paths<p> - -Starting with version 2.10 there are now several search paths for files needed -by the linker: One for libraries, one for object files and one for config -files. - - -<sect1>Library search path<p> - -The library search path contains in this order: - -<enum> -<item>The current directory. -<item>A compiled in library path which is often <tt>/usr/lib/cc65/lib</tt> on - Linux systems. -<item>The value of the environment variable <tt/LD65_LIB/ if it is defined. -<item>A subdirectory named <tt/lib/ of the directory defined in the environment - variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt><ref id="option--lib-path" - name="--lib-path"></tt> option on the command line. -</enum> - - -<sect1>Object file search path<p> - -The object file search path contains in this order: - -<enum> -<item>The current directory. -<item>A compiled in directory which is often <tt>/usr/lib/cc65/obj</tt> on - Linux systems. -<item>The value of the environment variable <tt/LD65_OBJ/ if it is defined. -<item>A subdirectory named <tt/obj/ of the directory defined in the environment - variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt><ref id="option--obj-path" - name="--obj-path"></tt> option on the command line. -</enum> - - -<sect1>Config file search path<p> - -The config file search path contains in this order: - -<enum> -<item>The current directory. -<item>A compiled in directory which is often <tt>/usr/lib/cc65/cfg</tt> on - Linux systems. -<item>The value of the environment variable <tt/LD65_CFG/ if it is defined. -<item>A subdirectory named <tt/cfg/ of the directory defined in the environment - variable <tt/CC65_HOME/, if it is defined. -<item>Any directory added with the <tt><ref id="option--cfg-path" - name="--cfg-path"></tt> option on the command line. -</enum> - - - -<sect>Detailed workings<p> - -The linker does several things when combining object modules: - -First, the command line is parsed from left to right. For each object file -encountered (object files are recognized by a magic word in the header, so -the linker does not care about the name), imported and exported -identifiers are read from the file and inserted in a table. If a library -name is given (libraries are also recognized by a magic word, there are no -special naming conventions), all modules in the library are checked if an -export from this module would satisfy an import from other modules. All -modules where this is the case are marked. If duplicate identifiers are -found, the linker issues a warning. - -This procedure (parsing and reading from left to right) does mean, that a -library may only satisfy references for object modules (given directly or from -a library) named <em/before/ that library. With the command line - -<tscreen><verb> - ld65 crt0.o clib.lib test.o -</verb></tscreen> - -the module test.o may not contain references to modules in the library -clib.lib. If this is the case, you have to change the order of the modules -on the command line: - -<tscreen><verb> - ld65 crt0.o test.o clib.lib -</verb></tscreen> - -Step two is, to read the configuration file, and assign start addresses -for the segments and define any linker symbols (see <ref id="config-files" -name="Configuration files">). - -After that, the linker is ready to produce an output file. Before doing that, -it checks its data for consistency. That is, it checks for unresolved -externals (if the output format is not relocatable) and for symbol type -mismatches (for example a zero page symbol is imported by a module as absolute -symbol). - -Step four is, to write the actual target files. In this step, the linker will -resolve any expressions contained in the segment data. Circular references are -also detected in this step (a symbol may have a circular reference that goes -unnoticed if the symbol is not used). - -Step five is to output a map file with a detailed list of all modules, -segments and symbols encountered. - -And, last step, if you give the <tt><ref id="option-v" name="-v"></tt> switch -twice, you get a dump of the segment data. However, this may be quite -unreadable if you're not a developer:-) - - - -<sect>Configuration files<label id="config-files"><p> - -Configuration files are used to describe the layout of the output file(s). Two -major topics are covered in a config file: The memory layout of the target -architecture, and the assignment of segments to memory areas. In addition, -several other attributes may be specified. - -Case is ignored for keywords, that is, section or attribute names, but it is -<em/not/ ignored for names and strings. - - - -<sect1>Memory areas<p> - -Memory areas are specified in a <tt/MEMORY/ section. Lets have a look at an -example (this one describes the usable memory layout of the C64): - -<tscreen><verb> - MEMORY { - RAM1: start = $0800, size = $9800; - ROM1: start = $A000, size = $2000; - RAM2: start = $C000, size = $1000; - ROM2: start = $E000, size = $2000; - } -</verb></tscreen> - -As you can see, there are two ram areas and two rom areas. The names -(before the colon) are arbitrary names that must start with a letter, with -the remaining characters being letters or digits. The names of the memory -areas are used when assigning segments. As mentioned above, case is -significant for these names. - -The syntax above is used in all sections of the config file. The name -(<tt/ROM1/ etc.) is said to be an identifier, the remaining tokens up to the -semicolon specify attributes for this identifier. You may use the equal sign -to assign values to attributes, and you may use a comma to separate -attributes, you may also leave both out. But you <em/must/ use a semicolon to -mark the end of the attributes for one identifier. The section above may also -have looked like this: - -<tscreen><verb> - # Start of memory section - MEMORY - { - RAM1: - start $0800 - size $9800; - ROM1: - start $A000 - size $2000; - RAM2: - start $C000 - size $1000; - ROM2: - start $E000 - size $2000; - } -</verb></tscreen> - -There are of course more attributes for a memory section than just start and -size. Start and size are mandatory attributes, that means, each memory area -defined <em/must/ have these attributes given (the linker will check that). I -will cover other attributes later. As you may have noticed, I've used a -comment in the example above. Comments start with a hash mark (`#'), the -remainder of the line is ignored if this character is found. - - -<sect1>Segments<p> - -Let's assume you have written a program for your trusty old C64, and you would -like to run it. For testing purposes, it should run in the <tt/RAM/ area. So -we will start to assign segments to memory sections in the <tt/SEGMENTS/ -section: - -<tscreen><verb> - SEGMENTS { - CODE: load = RAM1, type = ro; - RODATA: load = RAM1, type = ro; - DATA: load = RAM1, type = rw; - BSS: load = RAM1, type = bss, define = yes; - } -</verb></tscreen> - -What we are doing here is telling the linker, that all segments go into the -<tt/RAM1/ memory area in the order specified in the <tt/SEGMENTS/ section. So -the linker will first write the <tt/CODE/ segment, then the <tt/RODATA/ -segment, then the <tt/DATA/ segment - but it will not write the <tt/BSS/ -segment. Why? Enter the segment type: For each segment specified, you may also -specify a segment attribute. There are four possible segment attributes: - -<tscreen><verb> - ro means readonly - rw means read/write - bss means that this is an uninitialized segment - zp a zeropage segment -</verb></tscreen> - -So, because we specified that the segment with the name BSS is of type bss, -the linker knows that this is uninitialized data, and will not write it to an -output file. This is an important point: For the assembler, the <tt/BSS/ -segment has no special meaning. You specify, which segments have the bss -attribute when linking. This approach is much more flexible than having one -fixed bss segment, and is a result of the design decision to supporting an -arbitrary segment count. - -If you specify "<tt/type = bss/" for a segment, the linker will make sure that -this segment does only contain uninitialized data (that is, zeroes), and issue -a warning if this is not the case. - -For a <tt/bss/ type segment to be useful, it must be cleared somehow by your -program (this happens usually in the startup code - for example the startup -code for cc65 generated programs takes care about that). But how does your -code know, where the segment starts, and how big it is? The linker is able to -give that information, but you must request it. This is, what we're doing with -the "<tt/define = yes/" attribute in the <tt/BSS/ definitions. For each -segment, where this attribute is true, the linker will export three symbols. - -<tscreen><verb> - __NAME_LOAD__ This is set to the address where the - segment is loaded. - __NAME_RUN__ This is set to the run address of the - segment. We will cover run addresses - later. - __NAME_SIZE__ This is set to the segment size. -</verb></tscreen> - -Replace <tt/NAME/ by the name of the segment, in the example above, this would -be <tt/BSS/. These symbols may be accessed by your code. - -Now, as we've configured the linker to write the first three segments and -create symbols for the last one, there's only one question left: Where does -the linker put the data? It would be very convenient to have the data in a -file, wouldn't it? - -<sect1>Output files<p> - -We don't have any files specified above, and indeed, this is not needed in a -simple configuration like the one above. There is an additional attribute -"file" that may be specified for a memory area, that gives a file name to -write the area data into. If there is no file name given, the linker will -assign the default file name. This is "a.out" or the one given with the -<tt><ref id="option-o" name="-o"></tt> option on the command line. Since the -default behaviour is ok for our purposes, I did not use the attribute in the -example above. Let's have a look at it now. - -The "file" attribute (the keyword may also be written as "FILE" if you like -that better) takes a string enclosed in double quotes (`"') that specifies the -file, where the data is written. You may specify the same file several times, -in that case the data for all memory areas having this file name is written -into this file, in the order of the memory areas defined in the <tt/MEMORY/ -section. Let's specify some file names in the <tt/MEMORY/ section used above: - -<tscreen><verb> - MEMORY { - RAM1: start = $0800, size = $9800, file = %O; - ROM1: start = $A000, size = $2000, file = "rom1.bin"; - RAM2: start = $C000, size = $1000, file = %O; - ROM2: start = $E000, size = $2000, file = "rom2.bin"; - } -</verb></tscreen> - -The <tt/%O/ used here is a way to specify the default behaviour explicitly: -<tt/%O/ is replaced by a string (including the quotes) that contains the -default output name, that is, "a.out" or the name specified with the <tt><ref -id="option-o" name="-o"></tt> option on the command line. Into this file, the -linker will first write any segments that go into <tt/RAM1/, and will append -then the segments for <tt/RAM2/, because the memory areas are given in this -order. So, for the RAM areas, nothing has really changed. - -We've not used the ROM areas, but we will do that below, so we give the file -names here. Segments that go into <tt/ROM1/ will be written to a file named -"rom1.bin", and segments that go into <tt/ROM2/ will be written to a file -named "rom2.bin". The name given on the command line is ignored in both cases. - -Assigning an empty file name for a memory area will discard the data written -to it. This is useful, if the memory area has segments assigned that are empty -(for example because they are of type bss). In that case, the linker will -create an empty output file. This may be suppressed by assigning an empty file -name to that memory area. - -The <tt/%O/ sequence is also allowed inside a string. So using - -<tscreen><verb> - MEMORY { - ROM1: start = $A000, size = $2000, file = "%O-1.bin"; - ROM2: start = $E000, size = $2000, file = "%O-2.bin"; - } -</verb></tscreen> - -would write two files that start with the name of the output file specified on -the command line, with "-1.bin" and "-2.bin" appended respectively. Because -'%' is used as an escape char, the sequence "%%" has to be used if a single -percent sign is required. - -<sect1>LOAD and RUN addresses (ROMable code)<p> - -Let us look now at a more complex example. Say, you've successfully tested -your new "Super Operating System" (SOS for short) for the C64, and you -will now go and replace the ROMs by your own code. When doing that, you -face a new problem: If the code runs in RAM, we need not to care about -read/write data. But now, if the code is in ROM, we must care about it. -Remember the default segments (you may of course specify your own): - -<tscreen><verb> - CODE read only code - RODATA read only data - DATA read/write data - BSS uninitialized data, read/write -</verb></tscreen> - -Since <tt/BSS/ is not initialized, we must not care about it now, but what -about <tt/DATA/? <tt/DATA/ contains initialized data, that is, data that was -explicitly assigned a value. And your program will rely on these values on -startup. Since there's no other way to remember the contents of the data -segment, than storing it into one of the ROMs, we have to put it there. But -unfortunately, ROM is not writable, so we have to copy it into RAM before -running the actual code. - -The linker won't copy the data from ROM into RAM for you (this must be done by -the startup code of your program), but it has some features that will help you -in this process. - -First, you may not only specify a "<tt/load/" attribute for a segment, but -also a "<tt/run/" attribute. The "<tt/load/" attribute is mandatory, and, if -you don't specify a "<tt/run/" attribute, the linker assumes that load area -and run area are the same. We will use this feature for our data area: - -<tscreen><verb> - SEGMENTS { - CODE: load = ROM1, type = ro; - RODATA: load = ROM2, type = ro; - DATA: load = ROM2, run = RAM2, type = rw, define = yes; - BSS: load = RAM2, type = bss, define = yes; - } -</verb></tscreen> - -Let's have a closer look at this <tt/SEGMENTS/ section. We specify that the -<tt/CODE/ segment goes into <tt/ROM1/ (the one at $A000). The readonly data -goes into <tt/ROM2/. Read/write data will be loaded into <tt/ROM2/ but is run -in <tt/RAM2/. That means that all references to labels in the <tt/DATA/ -segment are relocated to be in <tt/RAM2/, but the segment is written to -<tt/ROM2/. All your startup code has to do is, to copy the data from its -location in <tt/ROM2/ to the final location in <tt/RAM2/. - -So, how do you know, where the data is located? This is the second point, -where you get help from the linker. Remember the "<tt/define/" attribute? -Since we have set this attribute to true, the linker will define three -external symbols for the data segment that may be accessed from your code: - -<tscreen><verb> - __DATA_LOAD__ This is set to the address where the segment - is loaded, in this case, it is an address in - ROM2. - __DATA_RUN__ This is set to the run address of the segment, - in this case, it is an address in RAM2. - __DATA_SIZE__ This is set to the segment size. -</verb></tscreen> - -So, what your startup code must do, is to copy <tt/__DATA_SIZE__/ bytes from -<tt/__DATA_LOAD__/ to <tt/__DATA_RUN__/ before any other routines are called. -All references to labels in the <tt/DATA/ segment are relocated to <tt/RAM2/ -by the linker, so things will work properly. - -There's a library subroutine called <tt/copydata/ (in a module named -<tt/copydata.s/) that might be used to do actual copying. Be sure to have a -look at it's inner workings before using it! - - -<sect1>Other MEMORY area attributes<p> - -There are some other attributes not covered above. Before starting the -reference section, I will discuss the remaining things here. - -You may request symbols definitions also for memory areas. This may be -useful for things like a software stack, or an i/o area. - -<tscreen><verb> - MEMORY { - STACK: start = $C000, size = $1000, define = yes; - } -</verb></tscreen> - -This will define some external symbols that may be used in your code: - -<tscreen><verb> - __STACK_START__ This is set to the start of the memory - area, $C000 in this example. - __STACK_SIZE__ The size of the area, here $1000. - __STACK_LAST__ This is NOT the same as START+SIZE. - Instead, it it defined as the first - address that is not used by data. If we - don't define any segments for this area, - the value will be the same as START. - __STACK_FILEOFFS__ The binary offset in the output file. This - is not defined for relocatable output file - formats (o65). -</verb></tscreen> - -A memory section may also have a type. Valid types are - -<tscreen><verb> - ro for readonly memory - rw for read/write memory. -</verb></tscreen> - -The linker will assure, that no segment marked as read/write or bss is put -into a memory area that is marked as readonly. - -Unused memory in a memory area may be filled. Use the "<tt/fill = yes/" -attribute to request this. The default value to fill unused space is zero. If -you don't like this, you may specify a byte value that is used to fill these -areas with the "<tt/fillval/" attribute. If there is no "<tt/fillval/" -attribute for the segment, the "<tt/fillval/" attribute of the memory area (or -its default) is used instead. This means that the value may also be used to -fill unfilled areas generated by the assemblers <tt/.ALIGN/ and <tt/.RES/ -directives. - -The symbol <tt/%S/ may be used to access the default start address (that is, -the one defined in the <ref id="FEATURES" name="FEATURES"> section, or the -value given on the command line with the <tt><ref id="option-S" name="-S"></tt> -option). - -To support systems with banked memory, a special attribute named <tt/bank/ is -available. The attribute value is an arbitrary 32 bit integer. The assembler -has a builtin function named <tt/.BANK/ which may be used with an argument -that has a segment reference (for example a symbol). The result of this -function is the value of the bank attribute for the run memory area of the -segment. - - -<sect1>Other SEGMENT attributes<p> - -Segments may be aligned to some memory boundary. Specify "<tt/align = num/" to -request this feature. Num must be a power of two. To align all segments on a -page boundary, use - -<tscreen><verb> - SEGMENTS { - CODE: load = ROM1, type = ro, align = $100; - RODATA: load = ROM2, type = ro, align = $100; - DATA: load = ROM2, run = RAM2, type = rw, define = yes, - align = $100; - BSS: load = RAM2, type = bss, define = yes, align = $100; - } -</verb></tscreen> - -If an alignment is requested, the linker will add enough space to the output -file, so that the new segment starts at an address that is dividable by the -given number without a remainder. All addresses are adjusted accordingly. To -fill the unused space, bytes of zero are used, or, if the memory area has a -"<tt/fillval/" attribute, that value. Alignment is always needed, if you have -used the <tt/.ALIGN/ command in the assembler. The alignment of a segment -must be equal or greater than the alignment used in the <tt/.ALIGN/ command. -The linker will check that, and issue a warning, if the alignment of a segment -is lower than the alignment requested in an <tt/.ALIGN/ command of one of the -modules making up this segment. - -For a given segment you may also specify a fixed offset into a memory area or -a fixed start address. Use this if you want the code to run at a specific -address (a prominent case is the interrupt vector table which must go at -address $FFFA). Only one of <tt/ALIGN/ or <tt/OFFSET/ or <tt/START/ may be -specified. If the directive creates empty space, it will be filled with zero, -of with the value specified with the "<tt/fillval/" attribute if one is given. -The linker will warn you if it is not possible to put the code at the -specified offset (this may happen if other segments in this area are too -large). Here's an example: - -<tscreen><verb> - SEGMENTS { - VECTORS: load = ROM2, type = ro, start = $FFFA; - } -</verb></tscreen> - -or (for the segment definitions from above) - -<tscreen><verb> - SEGMENTS { - VECTORS: load = ROM2, type = ro, offset = $1FFA; - } -</verb></tscreen> - -The "<tt/align/", "<tt/start/" and "<tt/offset/" attributes change placement -of the segment in the run memory area, because this is what is usually -desired. If load and run memory areas are equal (which is the case if only the -load memory area has been specified), the attributes will also work. There is -also an "<tt/align_load/" attribute that may be used to align the start of the -segment in the load memory area, in case different load and run areas have -been specified. There are no special attributes to set start or offset for -just the load memory area. - -A "<tt/fillval/" attribute may not only be specified for a memory area, but -also for a segment. The value must be an integer between 0 and 255. It is used -as fill value for space reserved by the assemblers <tt/.ALIGN/ and <tt/.RES/ -commands. It is also used as fill value for space between sections (part of a -segment that comes from one object file) caused by alignment, but not for -space that preceeds the first section. - -To suppress the warning, the linker issues if it encounters a segment that is -not found in any of the input files, use "<tt/optional=yes/" as additional -segment attribute. Be careful when using this attribute, because a missing -segment may be a sign of a problem, and if you're suppressing the warning, -there is no one left to tell you about it. - -<sect1>The FILES section<p> - -The <tt/FILES/ section is used to support other formats than straight binary -(which is the default, so binary output files do not need an explicit entry -in the <tt/FILES/ section). - -The <tt/FILES/ section lists output files and as only attribute the format of -each output file. Assigning binary format to the default output file would -look like this: - -<tscreen><verb> - FILES { - %O: format = bin; - } -</verb></tscreen> - -The only other available output format is the o65 format specified by Andre -Fachat (see the <htmlurl url="http://www.6502.org/users/andre/o65/fileformat.html" -name="6502 binary relocation format specification">). It is defined like this: - -<tscreen><verb> - FILES { - %O: format = o65; - } -</verb></tscreen> - -The necessary o65 attributes are defined in a special section labeled -<tt/FORMAT/. - - - -<sect1>The FORMAT section<p> - -The <tt/FORMAT/ section is used to describe file formats. The default (binary) -format has currently no attributes, so, while it may be listed in this -section, the attribute list is empty. The second supported format, -<htmlurl url="http://www.6502.org/users/andre/o65/fileformat.html" name="o65">, -has several attributes that may be defined here. - -<tscreen><verb> - FORMATS { - o65: os = lunix, version = 0, type = small, - import = LUNIXKERNEL, - export = _main; - } -</verb></tscreen> - - - -<sect1>The FEATURES section<label id="FEATURES"><p> - -In addition to the <tt/MEMORY/ and <tt/SEGMENTS/ sections described above, the -linker has features that may be enabled by an additional section labeled -<tt/FEATURES/. - - -<sect2>The CONDES feature<p> - -<tt/CONDES/ is used to tell the linker to emit module constructor/destructor -tables. - -<tscreen><verb> - FEATURES { - CONDES: segment = RODATA, - type = constructor, - label = __CONSTRUCTOR_TABLE__, - count = __CONSTRUCTOR_COUNT__; - } -</verb></tscreen> - -The <tt/CONDES/ feature has several attributes: - -<descrip> - - <tag><tt>segment</tt></tag> - - This attribute tells the linker into which segment the table should be - placed. If the segment does not exist, it is created. - - - <tag><tt>type</tt></tag> - - Describes the type of the routines to place in the table. Type may be one of - the predefined types <tt/constructor/, <tt/destructor/, <tt/interruptor/, or - a numeric value between 0 and 6. - - - <tag><tt>label</tt></tag> - - This specifies the label to use for the table. The label points to the start - of the table in memory and may be used from within user written code. - - - <tag><tt>count</tt></tag> - - This is an optional attribute. If specified, an additional symbol is defined - by the linker using the given name. The value of this symbol is the number - of entries (<em/not/ bytes) in the table. While this attribute is optional, - it is often useful to define it. - - - <tag><tt>order</tt></tag> - - Optional attribute that takes one of the keywords <tt/increasing/ or - <tt/decreasing/ as an argument. Specifies the sorting order of the entries - within the table. The default is <tt/increasing/, which means that the - entries are sorted with increasing priority (the first entry has the lowest - priority). "Priority" is the priority specified when declaring a symbol as - <tt/.CONDES/ with the assembler, higher values mean higher priority. You may - change this behaviour by specifying <tt/decreasing/ as the argument, the - order of entries is reversed in this case. - - Please note that the order of entries with equal priority is undefined. - - <tag><tt>import</tt></tag> - - This attribute defines a valid symbol name, that is added as an import - to the modules defining a constructor/desctructor of the given type. - This can be used to force linkage of a module if this module exports the - requested symbol. - -</descrip> - -Without specifying the <tt/CONDES/ feature, the linker will not create any -tables, even if there are <tt/condes/ entries in the object files. - -For more information see the <tt/.CONDES/ command in the <htmlurl -url="ca65.html" name="ca65 manual">. - - -<sect2>The STARTADDRESS feature<p> - -<tt/STARTADDRESS/ is used to set the default value for the start address, -which can be referenced by the <tt/%S/ symbol. The builtin default for the -linker is $200. - -<tscreen><verb> - FEATURES { - # Default start address is $1000 - STARTADDRESS: default = $1000; - } -</verb></tscreen> - -Please note that order is important: The default start address must be defined -<em/before/ the <tt/%S/ symbol is used in the config file. This does usually -mean, that the <tt/FEATURES/ section has to go to the top of the config file. - - - -<sect1>The SYMBOLS section<label id="SYMBOLS"><p> - -The configuration file may also be used to define symbols used in the link -stage or to force symbols imports. This is done in the SYMBOLS section. The -symbol name is followed by a colon and symbol attributes. - -The following symbol attributes are supported: - -<descrip> - - <tag><tt>addrsize</tt></tag> - - The <tt/addrsize/ attribute specifies the address size of the symbol and - may be one of -<itemize> - <item><tt/zp/, <tt/zeropage/ or <tt/direct/ - <item><tt/abs/, <tt/absolute/ or <tt/near/ - <item><tt/far/ - <item><tt/long/ or <tt/dword/. -</itemize> - -Without this attribute, the default address size is <tt/abs/. - - <tag><tt>type</tt></tag> - - This attribute is mandatory. Its value is one of <tt/export/, <tt/import/ or - <tt/weak/. <tt/export/ means that the symbol is defined and exported from - the linker config. <tt/import/ means that an import is generated for this - symbol, eventually forcing a module that exports this symbol to be included - in the output. <tt/weak/ is similar as <tt/export/. However, the symbol is - only defined if it is not defined elsewhere. - - <tag><tt>value</tt></tag> - - This must only be given for symbols of type <tt/export/ or <tt/weak/. It - defines the value of the symbol and may be an expression. - -</descrip> - -The following example defines the stack size for an application, but allows -the programmer to override the value by specifying <tt/--define -__STACKSIZE__=xxx/ on the command line. - -<tscreen><verb> - SYMBOLS { - # Define the stack size for the application - __STACKSIZE__: type = weak, value = $800; - } -</verb></tscreen> - - - -<sect1>Builtin configurations<p> - -The builtin configurations are part of the linker source. They can be retrieved -with <tt/--dump-config/ and don't have a special format. So if you need a -special configuration, it's a good idea to start with the builtin configuration -for your system. In a first step, just replace <tt/-t target/ by <tt/-C -configfile/. Then go on and modify the config file to suit your needs. - - - -<sect1>Secondary configurations<p> - -Several machine specific binary packages are distributed together with secondary -configurations (in the cfg directory). These configurations can be used with -<tt/-C configfile/ too. - - - -<sect>Special segments<p> - -The builtin config files do contain segments that have a special meaning for -the compiler and the libraries that come with it. If you replace the builtin -config files, you will need the following information. - -<sect1>INIT<p> - -The INIT segment is used for initialization code that may be reused once -execution reaches main() - provided that the program runs in RAM. You -may for example add the INIT segment to the heap in really memory -constrained systems. - -<sect1>LOWCODE<p> - -For the LOWCODE segment, it is guaranteed that it won't be banked out, so it -is reachable at any time by interrupt handlers or similar. - -<sect1>STARTUP<p> - -This segment contains the startup code which initializes the C software stack -and the libraries. It is placed in its own segment because it needs to be -loaded at the lowest possible program address on several platforms. - -<sect1>ZPSAVE<p> - -The ZPSAVE segment contains the original values of the zeropage locations used -by the ZEROPAGE segment. It is placed in its own segment because it must not be -initialized. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the linker, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>Copyright<p> - -ld65 (and all cc65 binutils) are (C) Copyright 1998-2005 Ullrich von -Bassewitz. For usage of the binaries and/or sources the following -conditions do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - - - -</article> diff --git a/doc/library.sgml b/doc/library.sgml deleted file mode 100644 index 29a8ca063..000000000 --- a/doc/library.sgml +++ /dev/null @@ -1,251 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>cc65 Library Overview -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2000-12-02, 2002-11-26 - -<abstract> -An overview over the runtime and C libraries that come with the cc65 compiler, -including a discussion of the differences to the ISO standard. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains a short overview of the libraries available for the cc65 C -compiler. Please have a look at the <htmlurl url="funcref.html" name="function -reference"> for a list function by function. Since the function reference is -not complete (I'm working on that) it may happen that you don't find a -specific function. In this case, have a look into the header files. All -functions, that are not defined by the ISO C standard have a short comment in -the headers, explaining their use. - - - -<sect>ISO C compatible library<p> - -The C library contains a large subset of the ISO C library. Functions are -usually missing in areas, where there is no support on typical 6502 systems. -Wide character sets are an example for this. - -I will not go into detail about the ISO functions. If a function is not -mentioned here explicitly, expect it to be available and to behave as defined -in the C standard. - -Functions that are <em/not/ available: - -<itemize> - <item><tt>tmpfile/tmpnam</tt> - <p> - <item><tt>system</tt> - <p> - <item>All functions that handle floating point numbers in some manner. - <p> - <item>The <tt/ldiv/ function (cc65 is currently not able to return structs - with a size not equal to 1, 2 or 4 bytes by value). - <p> - <item>All functions handling wide character strings. - <p> - <item>Signals and all related functions (having <tt/SIGSEGV/ would be - cool:-) - <p> - <item><tt>setbuf/setvbuf</tt> -</itemize> - -Functions not available on all supported systems: - -<itemize> - <item><tt>fopen/fread/fwrite/fclose/fputs/fgets/fscanf</tt>: The functions - are built on open/read/write/close. These latter functions are not available - on all systems. - <p> - <item><tt>ftell/fseek/fgetpos/fsetpos</tt>: Support depends on the - capabilities of the target machine. - <p> - <item><tt>rename/remove/rewind</tt>: Support depends on the capabilities of - the target machine. - <p> - <item><tt>time</tt>: Since many of the supported systems do not have a real - time clock, which means that the <tt/time/ function is not available. Please - note that the other functions from <tt/time.h/ <em/are/ available. -</itemize> - - -Functions that are limited in any way: - -<itemize> - <item><tt>strcspn/strpbrk/strspn</tt>: These functions have a length - limitation of 256 for the second string argument. Since this string gives a - character set, and there are only 256 distinct characters, this shouldn't be - a problem. - <p> - <item><tt>getenv</tt>: Since there is no such thing as an environment on all - supported systems, the <tt/getenv/ function will always return a <tt/NULL/ - pointer. - <p> - <item><tt>locale</tt>: There is no other locale than the "C" locale. The - native locale is identical to the "C" locale. -</itemize> - - -In addition to these limitations, some more functions are limited if inlined -versions are requested by using -Os: - -<itemize> - <item>The <tt/strlen/ function only works for strings with a maximum length - of 255 characters. - <p> - <item>The <tt/isxxx/ character classification functions from - <tt/<ctype.h>/ will give unpredictable results if the argument is not - in character range (0..255). This limitation may be removed by #undef'ing - the function name (when using <tt/-Os/, the functions are actually macros - that expand to inline assembler code, but the real functions are still - available if the macro definition is removed). -</itemize> - - - -<sect>CPU specific stuff - 6502.h<p> - -The header file 6502.h contains some functions that make only sense with the -6502 CPU. Examples are macros to insert more or less useful instructions into -your C code, or a function to call arbitrary machine language subroutines, -passing registers in and out. - - - -<sect>Target specific stuff<p> - -For each supported system there's a header file that contains calls or defines -specific for this system. So, when programming for the C64, include c64.h, for -the C128, include c128.h and so on. To make the task for the Commodore systems -easier, there is also a header file named cbm.h that will define stuff common -for all CBM systems, and include the header file for the specific target -system. - -The header files contain - -<itemize> - - <item>Defines for special keys (like function keys) - - <item>Defines for special characters (like the graphics characters) - - <item>Variables with a fixed address in memory that may be used to access - special hardware. For the C64 and C128 there is a variable struct named - <tt/SID/. Writing to the fields of this struct will write to the SID device - instead. Using these variables will make your program more readable and more - portable. Don't fear ineffective code when using these variables, the - compiler will translate reads and writes to these structs into direct memory - accesses. - - <item>Other routines that make only sense for a specific system. One example - are routines to write memory locations in the system bank for the CBM PET-II - family. - -</itemize> - - -<sect>Direct console I/O - <tt/conio.h/<p> - -The <tt/conio.h/ header file contains a large set of functions that do screen -and keyboard I/O. The functions will write directly to the screen or poll the -keyboard directly with no more help from the operating system than needed. -This has some disadvantages, but on the other side it's fast and reasonably -portable. conio implementations exist for the following targets: - - <itemize> - <item>apple2 - <item>apple2enh - <item>atari - <item>atmos - <item>c16 (works also for the c116 with up to 32K memory) - <item>c64 - <item>c128 - <item>plus4 (or expanded c16/c116) - <item>cbm510 (40 column video) - <item>cbm610 (all CBM series-II computers with 80 column video) - <item>geos-apple - <item>geos-cbm - <item>nes - <item>pet (all CBM PET systems except the 2001) - <item>vic20 - </itemize> - -The conio.h header file does also include the system specific header files -which define constants for special characters and keys. - - - -<sect>Using the joystick - <tt/joystick.h/<p> - -For systems that have a joystick, <tt/joystick.h/ will define a subroutine to -read the current value, including constants to evaluate the result of this -function. To help in writing portable code, the header file will define the -symbol <tt/__JOYSTICK__/ on systems that have a joystick. - - - -<sect>Using a mouse - <tt/mouse.h/<p> - -Some target machines support a mouse. Mouse support is currently available for -the following targets: - - <itemize> - <item>apple2 - <item>apple2enh - <item>atari - <item>c64 - <item>c128 - <item>cbm510 - </itemize> - -The available functions are declared in <tt/mouse.h/ To help writing portable -code, the header file will define the symbol <tt/__MOUSE__/ in systems that -support a mouse. - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>Copyright<p> - -This C runtime library implementation for the cc65 compiler is (C) -Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries -and/or sources the following conditions do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> - - - diff --git a/doc/lynx.sgml b/doc/lynx.sgml deleted file mode 100644 index 48c3d7d4a..000000000 --- a/doc/lynx.sgml +++ /dev/null @@ -1,360 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Atari Lynx specific information for cc65 -<author>Karri Kaksonen, <htmlurl url="mailto:karri@sipo.fi" name="karri@sipo.fi"> -Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2011-04-01 - -<abstract> -An overview over the Atari Lynx runtime system as it is implemented for the -cc65 C compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the Atari Lynx runtime system as it comes -with the cc65 C compiler. It describes the memory layout, Lynx specific header -files, available drivers, and any pitfalls specific to that platform. - -Please note that Lynx specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - - -<sect>Building your first Hello World application<p> - -Here is a small traditional Hello World program for the Atari Lynx. - -<tscreen><verb> -#include <lynx.h> -#include <tgi.h> -#include <6502.h> - -void main(void) { - tgi_install(tgi_static_stddrv); - tgi_init(); - CLI(); - while (tgi_busy()) - ; - tgi_clear(); - tgi_setcolor(COLOR_GREEN); - tgi_outtextxy(0, 0, "Hello World"); - tgi_updatedisplay(); - while (1) - ; -} -</verb></tscreen> - -The lynx.h contains all kind of system dependent things. - -The tgi.h contains the graphics driver functions. - -The 6502.h is needed for executing the CLI() command. - -As the Atari Lynx does not have ASCII characters available you need to use -the Tiny Graphics Interface library for producing letters on the screen. - -The cc65 compiler suite has a graphics library called "Tiny Graphics -Interface". This interface has some relocatable code. In order to use this -in your own program you need to load it at run time. - -Unfortunately the Lynx does not have a disk drive from where to load it. -Therefore you must already load it at compile time. The easiest way is to -automatically link it in statically from the Lynx C library. - -<tscreen><verb> -cl65 -t lynx -o game.lnx main.c -</verb></tscreen> - -This will create a bootable cart image called game.lnx - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the Lynx target -is a cart image. By specifying the config file lynx-bll.cfg the linker will -generate BLL download compatible binary files. - -It is of course possible to change this behaviour by using a modified startup -file and linker config. - -The bootloader used in the cc65 lynx library uses a very minimal bootloader -that does not check the cart or show a title screen. - -The advantage of this bootloader is that it allows creation of cart images to -many common formats. - -Cart sizes -<tscreen><verb> -Block size Rom size Description -512 bytes 128k Standard old games like Warbirds -1024 bytes 256k Most common format for homebrew. Also newer games like Lemmings -2048 bytes 512k Largest games like EOTB -</verb></tscreen> - -<sect>Memory layout<p> - -cc65 generated programs with the default setup run with the I/O area and the -kernal enabled, which gives a usable memory range of $200 - $C037. - -Special locations: -<tscreen><verb> - 0000 - 00FF Zero page - 0100 - 01FF Machine stack - - A058 - C037 Collision buffer - C038 - E017 Screen buffer 1 - E018 - FFF7 Screen buffer 0 - FFF8 - FFFF Hardware vectors -</verb></tscreen> - -<descrip> - <tag/Text screen/ - No conio support is currently available for the Lynx. - - <tag/Keyboard/ - The Lynx "flabode" keys, Opt 1, Pause and Opt 2 are implemented using the - conio interface. The only characters the keyboard is able to produce are - 'R' for Restart (Opt 1 + Pause), 'F' for flip (Opt 2 + Pause), - 'P' for pause, '1' for Opt 1, '2' for Opt 2, '3' for Opt 1 + Opt 2 and - '?' for all keys down at the same time. - - <tag/Stack/ - The C runtime stack is located at $C037 (or $A057 if collision - detection is enabled) and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - - <tag/Screen/ - The collision detection screen is at $A058 if it is enabled. The - double buffered screens are at $C038 and $E018. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing Lynx specific code may use the <tt/lynx.h/ header file. - - -<sect1>Lynx specific functions<p> - -<itemize> -<item>lynx_eeprom_erase -<item>lynx_eeprom_read -<item>lynx_eeprom_write -<item>lynx_eeread -<item>lynx_eewrite -<item>lynx_exec -<item>lynx_load -</itemize> - - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/lynx.h/ header file do -allow access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<descrip> - - <tag><tt/MIKEY/</tag> - The <tt/MIKEY/ structure allows access to MIKEY chip. See the <tt/_mikey.h/ - header file located in the include directory for the declaration of the - structure. - - <tag><tt/SUZY/</tag> - The <tt/SUZY/ structure allows access to SUZY chip. See the <tt/_suzy.h/ - header file located in the include directory for the declaration of the - structure. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -<descrip> - - <tag><tt/lynx-160-102-16.tgi (lynx_160_102_16)/</tag> - A TGI driver for the standard graphics mode (160×102 in 16 colors). - - The TGI driver is implemented as an interrupt driven dual buffering device. - To use it as a single-buffer device set draw page and view page to the same - value 0 or 1; - - The TGI driver has a few Lynx-specific extensions. - - Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx - sprite on screen. - - Calling tgi_flip() or tgi_ioctl(1, 0) will do a flip screen. - - Calling tgi_setbgcolor(bgcolor) or tgi_ioctl(2, bgindex) will set the text - background color to the index defined by bgindex. If bgindex is 0 then the - background color is transparent. - - To set the framerate of the display hardware call tgi_setframerate(rate) or - tgi_ioctl(3, rate). The supported framerates are 50, 60 and 75 frames per - second. Actually there is no real reason to use anything else than 75 frames - per second. - - To check if the drawing engine is busy with the previous swap you can - call tgi_busy or tgi_ioctl(4, 0). It returns 0 if idle and 1 if busy - - To update displays you can call tgi_updatedisplay() or tgi_ioctl(4, 1) it - will wait for the next VBL interrupt and set the draw buffer to the - view buffer. The draw buffer is also changed to (drawbuffer xor 1). - - You can also enable or disable collision detection by a call to - tgi_setcollisiondetection(active) or tgi_ioctl(5, active). The collision - result is located before the sprite structure by default in this driver. - - In order to reserve memory for the collision detection buffer you need to - specify lynx-coll.cfg as the configuration file to the linker. - -</descrip><p> - - -<sect1>Extended memory drivers<p> - -No extended memory drivers are currently available for the Lynx. - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/lynx-stdjoy.joy (lynx_stdjoy)/</tag> - A joystick driver for the standard buttons. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -No mouse drivers are currently available for the Lynx. - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/lynx-comlynx.ser (lynx_comlynx)/</tag> - A serial driver for the ComLynx port. - - The ComLynx port has Tx and Rx wired together. Every byte is sent - to all connected Lynxes. Only one Lynx can send at a time. There is no - protocol created for communication. You are on your own. - - If the Lynx returns framing error then it is likely that another Lynx is - sending data at the same time. - - The Lynx can also send a break and receive a break. The Lynx break is - recognized if the bit is down for 24 bit cycles or more. - - To send a break you just set the break bit. The length of the break depends - on how long this bit is down. - - The driver supports the baudrates: - <itemize> - <item>62500 - <item>31250 - <item>9600 - <item>7200 - <item>4800 - <item>3600 - <item>2400 - <item>1800 - <item>1200 - <item>600 - <item>300 - <item>150 - <item>134.5 - <item>110 - <item>75 - </itemize> - The parity bit supports MARK and SPACE. It also supports EVEN and ODD parity - but the parity bit is included in the calculation. Most of us don't want it - this way. But there is nothing we can do about it. - - The Lynx hardware will always check parity on incoming traffic. Currently - the driver cannot receive data from standard PC's due to this parity bug. - For working with Lynx to Lynx communication use EVEN parity. - - To send data to standard PC's use MARK or SPACE as parity setting. - - There is always only one stop bit. And the data length is always 8 bits. - - We have no handshaking available. Even software handshake is impossible - as ComLynx has only one wire for the data. - - Both transmit and receive are interrupt driven. - -</descrip><p> - - -<sect>Limitations<p> - - - -<sect>Cart access<p> - -At this point in time there is no support for the cart filesystem yet. I have -a <tt/lynx-cart-demo/ example project that uses an interrupt driven display, -has support for the cart filesystem and an abcmusic sound module. - -At some point in time we may find a way to rewrite these to fit the way the -cc65 drivers require. But for the time being you can create less portable -applications using these Lynx specific modules in <tt/lynx-cart-demo/. - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/nes.sgml b/doc/nes.sgml deleted file mode 100644 index c66b1f2ba..000000000 --- a/doc/nes.sgml +++ /dev/null @@ -1,197 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Nintendo Entertainment System specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> -<date>2005-07-17 - -<abstract> -An overview over the NES runtime system as it is implemented for the -cc65 C compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the NES runtime system as it comes -with the cc65 C compiler. It describes the memory layout, NES specific header -files, available drivers, and any pitfalls specific to that platform. - -Please note that NES specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the NES target -is a machine language program with an INES cartridge header. It is of course -possible to change this behaviour by using a modified startup file and linker -config. - -<sect>Memory layout<p> - -cc65 generated programs with the default setup run with the I/O area and a -CHR bank enabled, which gives a usable memory range of $8000 - $FFF3. -All boot ROM entry points may be called directly without additional code. - -Special locations: - -<descrip> - <tag/Text screen/ - The text screen is located at VRAM $2000. - - <tag/Stack/ - The C runtime stack is located at $7FFF and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing NES specific code may use the <tt/nes.h/ header file. - - -<sect1>NES specific functions<p> - -<itemize> -<item>waitvblank -<item>get_tv -</itemize> - - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/nes.inc/ include file do -allow access to hardware located in the address space. - -<descrip> - - <tag><tt/PPU/</tag> - The <tt/PPU/ defines allow access to the PPU chip. - - <tag><tt/APU/</tag> - The <tt/APU/ defines allow access to the APU chip. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -All drivers must be statically linked because no file I/O is available. -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -<descrip> - - <tag><tt/nes-64-56-2.tgi (nes_64_56_2)/</tag> - This driver features a resolution of 64×56 with 2 colors using the - CHR bank. - -</descrip><p> - - -<sect1>Extended memory drivers<p> - -No extended memory drivers are currently available for the NES. - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/nes-stdjoy.joy (nes_stdjoy)/</tag> - A joystick driver for the standard four buttons joypad is available. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -No mouse drivers are currently available for the NES. - - -<sect1>RS232 device drivers<p> - -No serial drivers are currently available for the NES. - - - -<sect>Limitations<p> - -<sect1>Disk I/O<p> - -The existing library for the NES doesn't implement C file -I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines. - -To be more concrete, this limitation means that you cannot use any of the -following functions (and a few others): - -<itemize> -<item>fclose -<item>fopen -<item>fread -<item>fprintf -<item>fputc -<item>fscanf -<item>fwrite -<item>... -</itemize> - - - -<sect>Other hints<p> - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> - - - diff --git a/doc/newvers.txt b/doc/newvers.txt deleted file mode 100644 index 059eb5c1f..000000000 --- a/doc/newvers.txt +++ /dev/null @@ -1,511 +0,0 @@ - -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. - - - - diff --git a/doc/od65.sgml b/doc/od65.sgml deleted file mode 100644 index 2668b0b86..000000000 --- a/doc/od65.sgml +++ /dev/null @@ -1,224 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>od65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2010-07-30 - -<abstract> -od65 is the object file dump utility. It is able to output most parts of -<htmlurl url="ca65.html" name="ca65"> generated object files in readable form. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - - -<sect>Overview<p> - -od65 is an object file dump utility. It is able to output most parts of -<htmlurl url="ca65.html" name="ca65"> generated object files in readable form. -Since the contents and format of the object files are not documented -elsewhere and may change at any time, this tool is a portable way to look at -the contents. - -Apart from curiosity, most people don't need to use this tool. - - - -<sect>Usage<p> - -The od65 utility dumps contents of one or more ca65 generated object file to -standard output. It has no cross-version compatibility, so you have to use -a version that matches the version of ca65 used to create the object files. - - -<sect1>Command line option overview<p> - -The program may be called as follows: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: od65 [options] file [options] [file] -Short options: - -h Help (this text) - -H Dump the object file header - -S Dump segments sizes - -V Print the version number and exit - -Long options: - --dump-all Dump all object file information - --dump-dbgsyms Dump debug symbols - --dump-exports Dump exported symbols - --dump-files Dump the source files - --dump-header Dump the object file header - --dump-imports Dump imported symbols - --dump-lineinfo Dump line information - --dump-options Dump object file options - --dump-segments Dump the segments in the file - --dump-segsize Dump segments sizes - --help Help (this text) - --version Print the version number and exit ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<label id="cmdline-opt-detail"><p> - -Here is a description of all the command line options: - -<descrip> - - <tag><tt>--dump-all</tt></tag> - - This will output all information, od65 is able to process. The option is a - shortcut for specifying all the other <tt/--dump/ options. - - - <tag><tt>--dump-dbgsyms</tt></tag> - - Dump all debug symbols contained in the object file. - - - <tag><tt>--dump-exports</tt></tag> - - Dump all exported symbols contained in the object file. - - - <tag><tt>--dump-files</tt></tag> - - Dump the file table contained in the object file. - - - <tag><tt>-H, --dump-header</tt></tag> - - Dump the object file header. - - - <tag><tt>--dump-imports</tt></tag> - - Dump the list of imported symbols contained in the object file. - - - <tag><tt>--dump-lineinfo</tt></tag> - - Dump the line info contained in the object file. - - - <tag><tt>--dump-segments</tt></tag> - - Dump the list of segments contained in the object file. - - - <tag><tt>--dump-scopes</tt></tag> - - Dump the scope (lexical level) information contained in the object file. - - - <tag><tt>-S, --dump-segsize</tt></tag> - - Dump the sizes of all segments contained in the object file. This option is - quite useful to determine the effect of measures that increase or decrease - code size. - - - <tag><tt>-h, --help</tt></tag> - - Print the short option summary shown above. - - - <tag><tt>-V, --version</tt></tag> - - Print the version number of the compiler. When submitting a bug report, - please include the operating system you're using, and the compiler - version. -</descrip> - - -<sect>Input and output<p> - -The converter will read one or more object files per invocation and write the -contents in readable format to standard output. Please note that you need to -specify any of the <tt/--dump/ options listed <ref id="cmdline-opt-detail" -name="above">, otherwise no useful output will be generated. - -Example output for the command -<tscreen><verb> -od65 --dump-header --dump-files t.o -</verb></tscreen> -<tscreen><verb> -t.o: - Header: - Magic: 0x616E7A55 - Version: 12 - Flags: 0x0001 (OBJ_FLAGS_DBGINFO) - Options: - Offset: 88 - Size: 9 - Files: - Offset: 97 - Size: 10 - Segments: - Offset: 107 - Size: 101 - Imports: - Offset: 208 - Size: 1 - Exports: - Offset: 209 - Size: 1 - Debug symbols: - Offset: 210 - Size: 55 - Line infos: - Offset: 265 - Size: 1 - String pool: - Offset: 266 - Size: 80 - Files: - Count: 1 - Index: 0 - Name: "t.s" - Size: 402 - Modification time: 1280498435 (Fri Jul 30 16:00:35 2010) -</verb></tscreen> - - -<sect>Bugs/Feedback<p> - -If you have problems using the converter, if you find any bugs, or if you're -doing something interesting with the code, I would be glad to hear from you. -Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>Copyright<p> - -od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the -binaries and/or sources the following conditions apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> - diff --git a/doc/pet.sgml b/doc/pet.sgml deleted file mode 100644 index 35e794db5..000000000 --- a/doc/pet.sgml +++ /dev/null @@ -1,261 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Commodore PET specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> -<date>2005-05-24 - -<abstract> -An overview over the PET runtime system as it is implemented for the cc65 C -compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the PET runtime system as it comes with the -cc65 C compiler. It describes the memory layout, PET specific header files, -available drivers, and any pitfalls specific to that platform. - -Please note that PET specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the PET target -is a machine language program with a one line BASIC stub, which calls the -machine language part via SYS. This means that a program can be loaded as -BASIC program and started with RUN. It is of course possible to change this -behaviour by using a modified startup file and linker config. - - -<sect>Memory layout<p> - -cc65 generated programs with the default setup run with the I/O area and the -kernal and BASIC ROM enabled, which gives a usable memory range of -$0400 - $7FFF (32KB machine). -All ROM entry points may be called directly without additional code. - -Special locations: - -<descrip> - <tag/Text screen/ - The text screen is located at $8000. - - <tag/Stack/ - The C runtime stack is located at $7FFF and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing PET specific code may use the <tt/pet.h/ or <tt/cbm.h/ -header files. Using the later may be an option when writing code for more than -one CBM platform, since it includes <tt/pet.h/ and declares several functions -common to all CBM platforms. - - -<sect1>PET specific functions<p> - -There are currently no special PET functions. - - - -<sect1>CBM specific functions<p> - -Some functions are available for all (or at least most) of the Commodore -machines. See the <htmlurl url="funcref.html" name="function reference"> for -declaration and usage. - -<itemize> -<item>cbm_close -<item>cbm_closedir -<item>cbm_k_setlfs -<item>cbm_k_setnam -<item>cbm_k_load -<item>cbm_k_save -<item>cbm_k_open -<item>cbm_k_close -<item>cbm_k_readst -<item>cbm_k_chkin -<item>cbm_k_ckout -<item>cbm_k_basin -<item>cbm_k_bsout -<item>cbm_k_clrch -<item>cbm_load -<item>cbm_open -<item>cbm_opendir -<item>cbm_read -<item>cbm_readdir -<item>cbm_save -<item>cbm_write -<item>get_tv -</itemize> - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/pet.h/ header file do allow -access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<descrip> - - <tag><tt/PIA1, PIA2/</tag> - Access to the two PIA (peripheral interface adapter) chips is available via - the <tt/PIA1/ and <tt/PIA2/ variables. The structure behind these variables - is explained in <tt/_pia.h/. - - <tag><tt/VIA/</tag> - The <tt/VIA/ structure allows access to the VIA (versatile interface - adapter). See the <tt/_6522.h/ header file located in the include - directory for the declaration of the structure. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -No graphics drivers are currently available for the PET. - - -<sect1>Extended memory drivers<p> - -No extended memory drivers are currently available for the PET. - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/pet-ptvjoy.joy (pet_ptvjoy)/</tag> - Driver for the Protovision 4-player adapter contributed by Groepaz. See - <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" - name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and - building instructions. Up to two joysticks are supported. - - <tag><tt/pet-stdjoy.joy (pet_stdjoy)/</tag> - Driver for the standard PET userport joystick. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -No mouse drivers are currently available for the PET. - - -<sect1>RS232 device drivers<p> - -No serial drivers are currently available for the PET. - - - -<sect>Limitations<p> - - - -<sect>Other hints<p> - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/. Since this is not -supported by BASIC, the following syntax was chosen: - -<tscreen><verb> - RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 -</verb></tscreen> - -<enum> -<item>Arguments are separated by spaces. -<item>Arguments may be quoted. -<item>Leading and trailing spaces around an argument are ignored. Spaces within - a quoted argument are allowed. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 10 arguments (including the program name) are - supported. -</enum> - - -<sect1>Program return code<p> - -The program return code (low byte) is passed back to BASIC by use of the -<tt/ST/ variable. - - -<sect1>Interrupts<p> - -The runtime for the PET uses routines marked as <tt/.INTERRUPTOR/ for -interrupt handlers. Such routines must be written as simple machine language -subroutines and will be called automatically by the interrupt handler code -when they are linked into a program. See the discussion of the <tt/.CONDES/ -feature in the <htmlurl url="ca65.html" name="assembler manual">. - - -<sect1>Using extended memory<p> - -The extended memory at $9000 of the CBM 8x96 may be added to the heap by using -the following code: - -<tscreen><verb> - /* Check for the existence of RAM */ - if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) { - /* Add it to the heap */ - _heapadd ((void *) 0x9000, 0x2000); - } -</verb></tscreen> - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/plus4.sgml b/doc/plus4.sgml deleted file mode 100644 index eefb85e21..000000000 --- a/doc/plus4.sgml +++ /dev/null @@ -1,270 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Commodore Plus/4 specific information for cc65 -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2003-12-14 - -<abstract> -An overview over the Plus/4 runtime system as it is implemented for the cc65 C -compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the Plus/4 runtime system as it comes with the -cc65 C compiler. It describes the memory layout, Plus/4 specific header files, -available drivers, and any pitfalls specific to that platform. - -Please note that Plus/4 specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more -information. - -Since the Plus/4 and the Commodore 16/116 are almost identical (the latter are -missing the 6551 ACIA and do only have 16KB of memory), the <htmlurl -url="c16.html" name="C16 documentation"> is also worth a look. The difference -between both cc65 targets is that the Plus/4 runtime uses banking to support -full 64K RAM, while the C16 does not use banking and supports up to 32K RAM. -Because banking is not needed, most C16 programs will be somewhat smaller than -the same program compiled for the Plus/4. However, programs compiled for the -C16 will always run on the Plus/4, while the reverse is not necessarily true. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the Plus/4 -target is a machine language program with a one line BASIC stub, which calls -the machine language part via SYS. This means that a program can be loaded as -BASIC program and started with RUN. It is of course possible to change this -behaviour by using a modified startup file and linker config. - - -<sect>Memory layout<p> - -cc65 generated programs with the default setup run with the kernal and basic -banked out. This gives a usable memory range of $1000 - $FD00. -Having the kernal and basic ROMs banked out means, that no ROM entry points -may be called directly from user code. - -Special locations: - -<descrip> - <tag/Text screen/ - The text screen is located at $C00 (as in the standard setup). - - <tag/Color RAM/ - The color RAM is located at $800 (standard location). - - <tag/Stack/ - The C runtime stack is located at $FCFF and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing Plus/4 specific code may use the <tt/plus4.h/ or <tt/cbm.h/ -header files. Using the later may be an option when writing code for more than -one CBM platform, since it includes <tt/plus4.h/ and declares several functions -common to all CBM platforms. - -Please note that most of the header file declarations from the <tt/plus4.h/ -header file are shared between the C16 and Plus/4 configurations. For this -reason, most of it is located in a common header file named <tt/cbm264.h/. - - - -<sect1>Plus/4 specific functions<p> - -There are currently no special Plus/4 functions. - - -<sect1>CBM specific functions<p> - -Some functions are available for all (or at least most) of the Commodore -machines. See the <htmlurl url="funcref.html" name="function reference"> for -declaration and usage. - -<itemize> -<item>cbm_close -<item>cbm_closedir -<item>cbm_k_setlfs -<item>cbm_k_setnam -<item>cbm_k_load -<item>cbm_k_save -<item>cbm_k_open -<item>cbm_k_close -<item>cbm_k_readst -<item>cbm_k_chkin -<item>cbm_k_ckout -<item>cbm_k_basin -<item>cbm_k_bsout -<item>cbm_k_clrch -<item>cbm_load -<item>cbm_open -<item>cbm_opendir -<item>cbm_read -<item>cbm_readdir -<item>cbm_save -<item>cbm_write -<item>get_tv -</itemize> - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/plus4.h/ header file do -allow access to hardware located in the address space. Some variables are -structures, accessing the struct fields will access the chip registers. - -<descrip> - - <tag><tt/TED/</tag> - The <tt/TED/ structure allows access to the TED chip. See the - <tt/_ted.h/ header file located in the include directory for the - declaration of the structure. - - <tag><tt/COLOR_RAM/</tag> - A character array that mirrors the color RAM of the Plus/4 at $0800. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -The names in the parentheses denote the symbols to be used for static linking of the drivers. - - -<sect1>Graphics drivers<p> - -No graphics drivers are currently available for the Plus/4. - - -<sect1>Extended memory drivers<p> - -No extended memory drivers are currently available for the Plus/4. - - -<sect1>Joystick drivers<p> - -<descrip> - - <tag><tt/plus4-stdjoy.joy (plus4_stdjoy)/</tag> - Supports up to two joysticks connected to the standard joysticks port of - the Plus/4. - -</descrip><p> - - -<sect1>Mouse drivers<p> - -Currently no drivers available (in fact, the API for loadable mouse drivers -does not exist). - - -<sect1>RS232 device drivers<p> - -<descrip> - - <tag><tt/plus4-stdser.ser (plus4_stdser)/</tag> - Driver for the 6551 ACIA chip built into the Plus/4. Supports up to 19200 - baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note - that because of the peculiarities of the 6551 chip transmits are not - interrupt driven, and the transceiver blocks if the receiver asserts flow - control because of a full buffer. - - You need an adapter to use the builtin port, since the output levels - available at the user port don't follow the RS232 standard. - -</descrip><p> - - - -<sect>Limitations<p> - - - -<sect>Other hints<p> - -<sect1>Passing arguments to the program<p> - -Command line arguments can be passed to <tt/main()/. Since this is not -supported by BASIC, the following syntax was chosen: - -<tscreen><verb> - RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 -</verb></tscreen> - -<enum> -<item>Arguments are separated by spaces. -<item>Arguments may be quoted. -<item>Leading and trailing spaces around an argument are ignored. Spaces within - a quoted argument are allowed. -<item>The first argument passed to <tt/main/ is the program name. -<item>A maximum number of 10 arguments (including the program name) are - supported. -</enum> - - - -<sect1>Program return code<p> - -The program return code (low byte) is passed back to BASIC by use of the -<tt/ST/ variable. - - -<sect1>Interrupts<p> - -The runtime for the Plus/4 uses routines marked as <tt/.INTERRUPTOR/ for -interrupt handlers. Such routines must be written as simple machine language -subroutines and will be called automatically by the interrupt handler code -when they are linked into a program. See the discussion of the <tt/.CONDES/ -feature in the <htmlurl url="ca65.html" name="assembler manual">. - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/readme.1st b/doc/readme.1st deleted file mode 100644 index 0409904cd..000000000 --- a/doc/readme.1st +++ /dev/null @@ -1,35 +0,0 @@ - -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 - - diff --git a/doc/smc.sgml b/doc/smc.sgml deleted file mode 100644 index b58fc51ab..000000000 --- a/doc/smc.sgml +++ /dev/null @@ -1,596 +0,0 @@ -<!doctype linuxdoc system> - -<article> -<title>ca65 Macros for Self Modifying Code -<author>Christian Krüger -<date>2012-02-19 - -<abstract> -The 'smc.inc' macro package for ca65 eases the use, increases the safeness and -self-explanation of 'self-modifying-code' (SMC). -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> -When reading assembler sources, self modifying code is often hard to identify -and applying it needs a lot of discipline. - -Since the cacheless 6502 is a thankful target of such kind of code, the macro -package will not only reduce this complexness, but also document the use. The -resulting source is more self-explanatory and so easier to maintain. - -While for general purposes SMC is not a desired form for implementations, it -can be quite useful for a small range of scenarios. Normally SMC will be -introduced when optimizing code in respect to: - -<itemize> -<item>speed and/or -<item>size. -</itemize> - -Please mind that SMC can only be applied for code in RAM, which means that a -general purpose library with SMC excludes ROM targets! - -The ca65 SMC macro package consists of two files: - -<itemize> -<item><tt>smc.inc</tt> -<item><tt>opcodes.inc</tt> -</itemize> - -The latter is only needed if you also plan to modify opcodes and not only data -within your code. - -<sect>Usage<p> -The use of the macros is quite simple: - -Original: - -<tscreen><verb> - PHA - JSR SUBROUTINE - PLA -</verb></tscreen> - -By applying SMC, the speed will now be increased by once cycle: - -SMC: - -<tscreen><verb> - SMC_StoreValue RestoreAccu - JSR SUBROUTINE -SMC RestoreAccu, { LDA #SMC_Value } -</verb></tscreen> - -The first line stores the value of the accu into the '<tt>RestoreAccu</tt>' -labeled SMC target. - -Please note: -<enum> -<item> for all SMC store or transfer operations, a second argument can be - given. This determines the register for the operation: - '<tt>SMC_StoreValue Label, y</tt>' will store the value of the - Y-register. - - If the second argument is missing, the accu will be used automatically. - -<item> The label targets a 'special SMC namespace'. It fits only to - destinations which are introduced with the macro '<tt>SMC</tt>'. A - normal label '<tt>RestoreAccu</tt>' wouldn't match and could even - coexist (even if you should abstain from doing so). - -<item> The macro '<tt>SMC_StoreValue</tt>' takes care, that the store - operation will occur on the value-position of a SMC-instruction. As - you will see, other macros influence other instruction part positions. - There is no consistency check, if the targeted SMC instruction acually - contains a value. Storing a 'value' on an immplied SMC instruction - would corrupt the following memory cell! -</enum> - -The second line needs no further explanation, this is just a placeholder for -some code in the example. - -The third line is the code line which is about to be modified. It has to start -with the '<tt>SMC</tt>' macro and must be labeled, so that the modification -can be designated. Then the unmodified code is given in curly braces. - -Please note the usage of the value placeholder 'SMC_Value'. Using such a -placeholder has two advantages: - -<enum> -<item> The code is better documented. It is clearly visible that the given - value is about to be changed. -<item> When examining an (initial) disassembly (e.g. in a debugger), these - placegolders can be better identified: They are fixed and, you may - notice that below, quite eye catching defined. -</enum> - -<sect1>Argument placeholders<p> - -There are four kinds of placeholders: - -<descrip> - - <label id="Address placeholder"> - <tag><tt>SMC_AbsAdr</tt></tag> - - Used to indicate an address. The value is '<tt>$FADE</tt>'. - - Example: <tt>STA SMC_AbsAdr</tt> - - - <label id="Zero-Page-Address placeholder"> - <tag><tt>SMC_ZpAdr</tt></tag> - - Used to indicate a zero-page-address. The value is '<tt>$00</tt>'. - - Example: <tt>LDA SMC_ZpAdr</tt> - - - <label id="Opcode placeholder"> - <tag><tt>SMC_Opcode</tt></tag> - - Used to indicate an instruction. The value is '<tt>NOP</tt>'. - - Example: <tt>SMC_Opcode</tt> - - - <label id="Immediate value placeholder"> - <tag><tt>SMC_Value</tt></tag> - - Used to indicate a value. The value is '<tt>$42</tt>'. - - Example: <tt>LDX #SMC_Value</tt> -</descrip> - -Attention: Often code is modified after the initial use - where using the -placeholders does not makes sense. Please mind also, that in very variable -expressions (e.g. opcode and argument is about to be changed), placeholders -can lead to unidentifyable code for a debugger/disassembler: - -<tt>SMC Example, { SMC_Opcode SMC_AbsAdr } </tt> - -Since the opcode is '<tt/NOP/', the value '<tt/$DE/' from '<tt/$FADE/' will -interpreted as opcode in a disassembler too. This breaks the correct -disassembly, because '<tt/$DE/' is interpreted as '<tt/DEC abx/'. Establishing -a valid placeholder instruction may be better: - -<tt>SMC Example, { sta SMC_AbsAdr } ; Note: Opcode will be modified too!</tt> - -<sect1>Accessing opcodes<p> - -Some macros are designed to access the instruction of a code line. To increase -readability, please use the opcodes as defined in the '<tt>opcodes.inc</tt>' -file. - -<descrip> - - <label id="Transfer opcode"> - <tag><tt>SMC_TransferOpcode label, opcode (, register)</tt></tag> - Loads and store an opcode to given SMC instruction. - - Example: - -<tscreen><verb> -SMC SumRegister, { LDA #10 } - JSR OUTPUT - SMC_TransferOpcode SumRegister, OPC_ADC_imm, x -</verb></tscreen> - -The macro above will load the opcode '<tt>ADC #</tt>' into the x - register -and stores it at the place of the '<tt>LDA #</tt>'. - - <label id="Load opcode"> - <tag><tt>SMC_LoadOpcode label (, register)</tt></tag> - Loads the opcode of a SMC line to the given register. - - Example: -<tscreen><verb> -SMC ShiftOrNothing, { LSL } - SMC_LoadOpcode ShiftOrNothing, y - CPY #OPC_NOP - BEQ Exit -</verb></tscreen> - - <label id="Store opcode"> - <tag><tt>SMC_StoreOpcode label (, register)</tt></tag> - Stores the value of the given register at the opcode place of a SMC line. - - Example: -<tscreen><verb> -SetBoldMode: - LDA #OPC_INX - SMC_StoreOpcode AdaptCharWidth - SMC_StoreOpcode AdaptUnderlineWidth - RTS - ... -SMC AdaptCharWidth, { NOP } - ... -SMC AdaptUnderlineWidth, { NOP } -</verb></tscreen> - -</descrip> - -<sect1>Accessing arguments<p> - -These marcos are determined to get, set and change arguments of instructions: - -<descrip> - - <label id="Change branch"> - <tag><tt>SMC_ChangeBranch label, destination (, register)</tt></tag> - - Used to modify the destination of a branch instruction. If the adress offset - exceeds the supported range of 8-bit of the 6502, a error will be thrown. - - Example: -<tscreen><verb> -Disable Handler: - SMC_ChangeBranch BranchToHandler, Exit - RTS - ... - LDA warning -SMC BranchToHandler, { BNE Handler } -Exit: - RTS -</verb></tscreen> - - - <label id="Transfer value"> - <tag><tt>SMC_TransferValue label, value (, register)</tt></tag> - - Changes the value of a SMC line. - - Example: -<tscreen><verb> -ClearDefault: - SMC_TransferValue LoadDefault, 0 - RTS - ... -SMC LoadDefault, { LDX #25 } -</verb></tscreen> - - - <label id="Load value"> - <tag><tt>SMC_LoadValue label (, register)</tt></tag> - - Retreives the value of a SMC line. - - Example: -<tscreen><verb> -ShowDefault: - SMC_LoadValue LoadDefault - JSR PrintValue - RTS - ... -SMC LoadDefault, { LDX #25 } -</verb></tscreen> - - - <label id="Store value"> - <tag><tt>SMC_StoreValue label (, register)</tt></tag> - - Stores the value in the register to given SMC line. - - Example: -<tscreen><verb> -InitCounters: - LDY #0 - SMC_StoreValue GetI, y - SMC_StoreValue GetJ, y - SMC_StoreValue GetK, y - ... -SMC GetI, { LDX #SMC_Value } - ... -SMC GetJ, { LDX #SMC_Value } - ... -SMC GetK, { LDX #SMC_Value } -</verb></tscreen> - - - <label id="Transfer low-byte"> - <tag><tt>SMC_TransferLowByte label, value (, register)</tt></tag> - - Does the same as '<tt>SMC_TransferValue</tt>' but should be used for - low-bytes of adresses for better readability. - - Example: -<tscreen><verb> -ActivateSecondDataSet: - SMC_TransferLowByte LoadData, $40 - RTS - ... -SMC LoadData, { LDA $2000 } -</verb></tscreen> - - - <label id="Load low-byte"> - <tag><tt>SMC_LoadLowByte label (, register)</tt></tag> - - Does the same as '<tt>SMC_LoadValue</tt>' but should be used for low-bytes - of adresses for better readability. - - Example: -<tscreen><verb> -IsSecondDataSetActive: - SMC_LoadLowByte LoadData, y - CPY #$40 - BNE NotActive - ... -SMC LoadData, { LDA $2000 } -</verb></tscreen> - - - <label id="Store low-byte"> - <tag><tt>SMC_StoreLowByte label (, register)</tt></tag> - - Does the same as '<tt>SMC_StoreValue</tt>' but should be used for low-bytes - of adresses for better readability. - - Example: -<tscreen><verb> -InitStructureBaseAddresses: - LDX #0 - SMC_StoreLowByte GetPlayerGraphic, x - SMC_StoreLowByte GetObjectGraphic, x - SMC_StoreLowByte StoreCollisionData, x - RTS - ... -SMC GetPlayerGraphic, { LDX $2000 } - ... -SMC GetObjectGraphic, { LDA $2100,x } - ... -SMC StoreCollisionData, { STY $2200 } -</verb></tscreen> - - - <label id="Transfer high-byte"> - <tag><tt>SMC_TransferHighByte label, value (, register)</tt></tag> - - Loads and stores the given value via the named register to the high-byte - adress portion of an SMC-instruction. - - Example: -<tscreen><verb> -PlaySFX: -SMC GetVolume { LDA $3200,x } - STA SoundOut - INX - BNE PlaySFX - ... -PlayOtherSound: - SMC_TransferHighByte GetVolume, $34 -</verb></tscreen> - - - <label id="Load high-byte"> - <tag><tt>SMC_LoadHighByte label (, register)</tt></tag> - - Loads the high-byte part of an SMC-instruction adress to the given register. - - Example: -<tscreen><verb> -PlaySFX: -SMC GetVolume { LDA $3200,x } - ... - SMC_LoadHighByte GetVolume - cmp #$34 - beq OtherSoundPlaying - ... -</verb></tscreen> - - - <label id="Store high-byte"> - <tag><tt>SMC_StoreHighByte label (, register)</tt></tag> - - Stores the high-byte adress part of an SMC-instruction from the given - register. - - Example: -<tscreen><verb> -SetupLevel2: - LDX #(>Level2Base) - SMC_StoreHighByte GetLevelData, x - SMC_StoreHighByte GetScreenData, x - SMC_StoreHighByte GetSoundData, x - RTS - ... -SMC GetLevelData, { LDA Level1Base+Data } - ... -SMC GetScreenData, { LDA Level1Base+Screen, x } - ... -SMC GetSoundData, { LDA Level1Base+Sound, y } -</verb></tscreen> - - - <label id="Transfer single adress"> - <tag><tt>SMC_TransferAddressSingle label, address (, register)</tt></tag> - - Transfers the contents of the given address via the given register to the - designated SMC instruction. - - Example: -<tscreen><verb> -PrintHello: - SMC_TransferAddressSingle GetChar, #HelloMsg - ... - LDX #0 -NextChar: -SMC GetChar, { LDA SMC_AbsAdr, x } - BEQ leave - JSR CharOut - INX - BNE NextChar -</verb></tscreen> - - - <label id="Transfer adress"> - <tag><tt>SMC_TransferAddress label, address</tt></tag> - - Loads contents of given address to A/X and stores the result to SMC - instruction. Allows reuse of register contents by using - '<tt>SMC_StoreAddress</tt>' for multiple SMC instruction modifications. - - Example: -<tscreen><verb> - SMC_TransferAddress JumpTo, #CloseChannel - ... -SMC JumpTo, { JMP OpenChannel } -</verb></tscreen> - - - <label id="Store address"> - <tag><tt>SMC_StoreAddress label</tt></tag> - - Stores the address value in a/x to a SMC instruction address position. - - Example: -<tscreen><verb> - SMC_StoreAddress GetData - ... -SMC GetData, { LDA SMC_AbsAdr } -</verb></tscreen> - -</descrip> - -<sect1>Operational macros<p> - -These marcos are determined to let read/modify/write opcodes work on parts of -SMC instructions. - -<descrip> - - <label id="Operate on value"> - <tag><tt>SMC_OperateOnValue opcode, label</tt></tag> - - Let given opcode work on the value part of a SMC instruction. - - Example: -<tscreen><verb> - SMC_OperateOnValue ASL, LoadMask ; shift mask to left - ... -SMC LoadMask, { LDA #$20 } -</verb></tscreen> - - <label id="Operate on low-byte"> - <tag><tt>SMC_OperateOnLowByte opcode, label</tt></tag> - - Same as '<tt/SMC_OperateOnValue/' but renamed for better readability when - accessing low-bytes of address. - - Example: -<tscreen><verb> - SMC_OperateOnLowByte DEC, AccessData - ... -SMC AccessData, { LDX Data } -</verb></tscreen> - - <label id="Operate on high-byte"> - <tag><tt>SMC_OperateOnHighByte opcode, label</tt></tag> - - Let the given opcode work on the high-byte part on a SMC-instruction. - - Example: -<tscreen><verb> -NextPage: - SMC_OperateOnHighByte INC, GetPageData - ... -SMC GetPageData, { LDA SourceData, X } -</verb></tscreen> -</descrip> - -<sect1>Scope macros<p> - -These marcos are determined to export and import SMC labels out of the current -file scope. Please handle with care! If you cannot abstain from leaving the -file scope, you should at least document the exported SMC lines very well. On -import side no checking is available if the SMC line is correct accessed (e.g. -invalid access to the value of an implied instruction)! - -<descrip> - <label id="Export SMC line under given name"> - <tag><tt>SMC_Export alias, label</tt></tag> - - SMC label will be exported under given alias. - - Example: -<tscreen><verb> -.proc GetValue -SMC LoadValue, { LDA #12 } - rts -.endproc - -SMC_Export GetValueLoader, GetValue::LoadValue -</verb></tscreen> - - <label id="Import SMC alias"> - <tag><tt>SMC_Import alias</tt></tag> - - SMC line is made accessible under given alias. - - Example: -<tscreen><verb> -SMC_Import GetValueLoader - ... - SMC_TransferValue GetValueLoader, #47 - ... -</verb></tscreen> -</descrip> - -<sect>A complex example<p> -Let's have a look on a quite sophisticated example for the usage of SMC. It -not only modifies code, but also the modification of the code is modified - -allowing reuse of some instructions. - -The code is from my 'memset()'implementation: - -<descrip> -<tscreen><verb> - 1: ... - 2: SMC_StoreAddress StoreAccuFirstSection - 3: - 4: StoreToFirstSection: - 5: SMC StoreAccuFirstSection, { sta SMC_AbsAdr, Y } - 6: ... - 7: RestoreCodeBranchBaseAdr: - 8: SMC FirstIncHighByte, { SMC_OperateOnHighByte inc, StoreAccuFirstSection } ; code will be overwritten to 'beq RestoreCode' (*) - 9: ... -10: SMC_TransferOpcode FirstIncHighByte, OPC_BEQ , x ; change code marked above with (*) -11: SMC_TransferValue FirstIncHighByte, #(restoreCode - RestoreCodeBranchBaseAdr-2), x ; set relative adress to 'RestoreCode' -12: ... -13: restoreCode: -14: SMC_TransferOpcode FirstIncHighByte, OPC_INC_abs , x ; restore original code... -15: SMC_TransferValue FirstIncHighByte, #(<(StoreToFirstSection+2)), x ; (second byte of inc contained low-byte of adress) -16: ... -</verb></tscreen> - -Some explanation: - -Line 2: The register pair A/X contains an address, which is stored on the -address location of a SMC line called 'StoreAccuFirstSection'. According to -cc65's calling convention, the low-byte is in accu while the high-byte is in -the X-register. - -Line 5: The (modified) address is accessed. - -Line 8: We have a line here, which is about to be modified (it begins with -SMC), but itself modifies code. Please note: Contrary to the rest of SMC-line -modifying macros, the 'OperateOn'-macros just expand their given arguments -into a single instruction line. These can be changed of course too. - -Line 10,11: These lines construct a branch operation for line 8: The -X-register will be used to change it from 'inc StoreAccuFirstSection+2' -(high-byte operation) to 'beq restoreCode'. Please note: To calculate the -relaive branch offset, we introduced a second label -('RestoreCodeBranchBaseAdr') for to calculate it. Some could also use the -internal name of the SMC label, but you should abstain to do so - it may be -changed in the future... - -Line 14,15: The original code from line 8 is reestablished. -</descrip> -</article> - diff --git a/doc/sp65.sgml b/doc/sp65.sgml deleted file mode 100644 index 32dead645..000000000 --- a/doc/sp65.sgml +++ /dev/null @@ -1,424 +0,0 @@ -<!doctype linuxdoc system> <!-- -*- text-mode -*- --> - -<article> -<title>sp65 Users Guide -<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> -<date>2012-03-11 - -<abstract> -sp65 is a sprite and bitmap utility that is part of the cc65 development suite. -It is used to convert graphics and bitmaps into the target formats of the -supported machines. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -sp65 is a tool that converts images from common formats into formats used -on the 6502 platforms that are the targets of the cc65 compiler suite. In -addition, it allows some very simple operation with loaded graphics data, like -using part of an image for further processing. - -The utility has been designed in a way that adding additional source or target -formats is easy. The final output is either binary, or C/assembler source. - - - -<sect>Usage<p> - - -<sect1>Command line option overview<p> - -The sp65 utility accepts the following options: - -<tscreen><verb> ---------------------------------------------------------------------------- -Usage: sp65 [options] file [options] [file] -Short options: - -V Print the version number and exit - -c fmt[,attrlist] Convert into target format - -h Help (this text) - -lc List all possible conversions - -r file[,attrlist] Read an input file - -v Increase verbosity - -w file[,attrlist] Write the output to a file - -Long options: - --convert-to fmt[,attrlist] Convert into target format - --help Help (this text) - --list-conversions List all possible conversions - --pop Restore the original loaded image - --read file[,attrlist] Read an input file - --slice x,y,w,h Generate a slice from the loaded bitmap - --verbose Increase verbosity - --version Print the version number and exit - --write file[,attrlist] Write the output to a file ---------------------------------------------------------------------------- -</verb></tscreen> - - -<sect1>Command line options in detail<p> - -Below is a description of all the command line options. For the concept of -attribute lists see <ref id="attr-lists" name="below">. - -<descrip> - - <label id="option--convert-to"> - <tag><tt>-c, --convert-to format[,attrlist]</tt></tag> - - Convert a bitmap into one of the supported target formats. The option - argument must at least contain the "format" attribute. For more attributes, - see section <ref id="conversions" name="Conversions">. - - - <label id="option--help"> - <tag><tt>-h, --help</tt></tag> - - Print the short option summary shown above. - - - <label id="option--list-conversions"> - <tag><tt>-lc, --list-conversions</tt></tag> - - Print a list of possible conversions. - - - <label id="option--pop"> - <tag><tt>--pop</tt></tag> - - Restore the working copy of the bitmap from the one originally loaded from - the file. This may for example be used when creating several output files - from one input file. - - - <label id="option--read"> - <tag><tt>-r, --read filename[,attrlist]</tt></tag> - - Read an input file. The option argument must at least contain the "name" - attribute. See <ref id="input-formats" name="input formats"> for more - information. - - - <label id="option-v"> - <tag><tt>-v, --verbose</tt></tag> - - Increase verbosity. Usually only needed for debugging purposes. You may use - this option more than one time for even more verbose output. - - - <label id="option-V"> - <tag><tt>-V, --version</tt></tag> - - Print the version number of the assembler. If you send any suggestions or - bugfixes, please include the version number. - - - <label id="option--write"> - <tag><tt>-w, --write filename[,attrlist]</tt></tag> - - Write an output file. The option argument must at least contain the "name" - attribute. See <ref id="output-formats" name="output formats"> for more - information. - -</descrip> -<p> - - - -<sect>Processing pipeline<label id="processing-pipeline"><p> - -sp65 consists of - -<itemize> -<item>Front ends that read graphics data, -<item>processors for graphics data, -<item>converters -<item>and output modules for several formats. -</itemize> - -These modules can be combined to a pipeline that reads data, does some -optional bitmap processing, converts the bitmap into a target format, and -writes this binary data to disk in one of several forms. - - - -<sect>Attribute lists<label id="attr-lists"><p> - -As described in <ref id="processing-pipeline" name="Processing pipeline">, -sp65 consists of lots of different modules that may be combined in different -ways, to convert an input bitmap to some output. - -Many of the processors and converters have options to change the way, they're -working. To avoid having lots of command line options that must be parsed on -high level and passed down to the relevant parts of the program, sp65 features -something called "attribute lists". Attribute lists are lists of -attribute/value pairs. These lists are parsed by the main program module -without any knowledge about their meaning. Lower level parts just grab the -attributes they need. - -In general, attribute lists look like this: - -<tscreen><verb> - attr1=val1[,attr2=val2[,...]] -</verb></tscreen> - -Instead of the comma, colons may also be used (even mixed). - -To simplify things and to make the most common options look "normal", some -mandatory attributes may be given without an attribute name. If the attribute -name is missing, the default name is determined by the position. For example, -the option <tt/<ref id="option--read" name="--read">/ does always need a file -name. The attribute name for the file name is "name". To avoid having to type - -<tscreen><verb> - sp65 --read name=ball.pcx ... -</verb></tscreen> - -the first attribute gets the default name "name" assigned. So if the first -attribute doesn't have a name, it is assumed that it is the file name. This -means that instead of the line above, one can also use - -<tscreen><verb> - sp65 --read ball.pcx ... -</verb></tscreen> - -The second attribute for <tt/--read/ is the format of the input file. So when -using - -<tscreen><verb> - sp65 --read ball.pic:pcx ... -</verb></tscreen> - -a PCX file named "ball.pic" is read. The long form would be - -<tscreen><verb> - sp65 --read name=ball.pic:format=pcx ... -</verb></tscreen> - -Changing the order of the attributes is possible only when explicitly -specifying the names of the attributes. Using - -<tscreen><verb> - sp65 --read pcx:ball.pic ... -</verb></tscreen> - -will make sp65 complain, because it tries to read a file named "pcx" with an -(unknown) format of "ball.pic". The following however will work: - -<tscreen><verb> - sp65 --read format=pcx:name=ball.pic ... -</verb></tscreen> - -The attributes that are valid for each processor or converter are listed -below. - - - -<sect>Input formats<label id="input-formats"><p> - -Input formats are either specified explicitly when using <tt/<ref -id="option--read" name="--read">/, or are determined by looking at the -extension of the file name given. - -<sect1>PCX<p> - -While sp65 is prepared for more, this is currently the only possible input -format. There are no additional attributes for this format. - - - -<sect>Conversions<label id="conversions"><p> - -<sect1>GEOS bitmap<p> - -The current bitmap working copy is converted to a GEOS compacted bitmap. This -format is used by several GEOS functions (i.e. 'BitmapUp') and is described -in 'The Official GEOS Programmers Reference Guide', chapter 4, section -'Bit-Mapped Graphics'. - - -<sect1>GEOS icon<p> - -The current bitmap working copy is converted to GEOS icon format. A GEOS icon -has the same format as a C64 high resolution sprite (24x21, monochrome, 63 -bytes). There are no additional attributes for this conversion. - - -<sect1>Koala image<p> - - -<sect1>Lynx sprite<p> - -Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size -of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by -102 pixels which makes very large sprites useless. - -The number per pixels is taken from the number of colors of the input bitmap. - -There are a few attributes that you can give to the conversion software. - -<descrip> - - <tag/mode/ - The first is what kind of encoding to use for the sprite. The attribute for - this is called "mode" and the possible values are "literal", "packed" or - "transparent". The default is "packed" if no mode is specified. - - The "literal" is a totally literal mode with no packing. In this mode the - number of pixels per scanline will be a multiple of 8 both right and left from - the action point. - - If the source bitmap edge ends with a color where the least significant bit is - one then there will be an extra 8 zero bits on that scan line. - - So if you are using totally literal sprites and intend to change them at - runtime then please add a single pixel border far left and far right with - zeros in order to prevent graphical glitches in the game. - - The standard encoding is called "packed". In this mode the sprite is packed - using run-length encoding and literal coding mixed for optimisation to - produce a small sprite. - - The last encoding mode "transparent" is like packed. But here we know that - the index 0 will be transparent so we can clip off all 0 pixels from the left - and right edge of the sprite. This will produce the smallest sprite possible - on the Lynx. The sprite is not rectangular anymore. - - <tag/ax/ - The sprite is painted around the Anchor point. The anchor point x can be - between 0 and the width of the sprite - 1. If anchor point x is zero then - painting the sprite in location 10,20 will set the left edge of the sprite - 10 pixels from the left of the Lynx screen. When the sprite is scaled by - hardware the anchor point stays in place and the sprite grows or shrinks - around the anchor point. The default value is 0 (left). - - <tag/ay/ - The sprite is painted around the Anchor point. The anchor point y can be - between 0 and the height of the sprite - 1. If anchor point y is zero then - painting the sprite in location 10,20 will set the top of the sprite 20 - pixels from the top of the Lynx screen. When the sprite is scaled by - hardware the anchor point stays in place and the sprite grows or shrinks - around the anchor point. The default value is 0 (top). - -</descrip> - -<sect1>VIC2 sprite<p> - - - - -<sect>Output formats<label id="output-formats"><p> - -Using <tt/<ref id="option--write" name="--write">/ it is possible to write -processed data to an output file. An attribute "name" is mandatory, it is used -as the file name for the output. The output format can be specified using an -attribute named "format". If this attribute doesn't exist, the output format -is determined by looking at the file name extension. - - -<sect1>Binary<p> - -For this format, the processed data is written to the output file in raw -binary format. There are no additional attributes (besides "name" and -"format") for this output format. - - -<sect1>Assembler code<p> - -For this format, the processed data is written to the output file in ca65 -assembler format. There are several attributes for this output format: - -<descrip> - - <tag/base/ - The value for this attribute specifies the numeric base for the data - values. It may be either 2, 10 or 16. The default is 16. If the base is - 2, the numbers are prefixed by '%', if the base is 16, the numbers are - prefixed by '$'. For base 10, there is no prefix. - - <tag/bytesperline/ - The value for this attribute specifies the number of bytes output in one - line of the assembler file. The default is 16. - - <tag/ident/ - This is an optional attribute. When given, the output processor will wrap - the data into a <tt/.PROC/ with the given name. In addition, three constants - are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/ - and <tt/HEIGHT/. - -</descrip> - - - -<sect1>C code<p> - -When using C output format, a small piece of C source code is generated that -defines the data containing the output in an array of <tt/unsigned char/. - -Possible attributes for this format are: - -<descrip> - <tag/base/ - The value for this attribute specifies the numeric base for the data values. - It may be either 10 or 16. The default is 16. If the base is 16, the numbers - are prefixed by 0x. For base 10, there is no prefix. - - <tag/bytesperline/ - The value for this attribute specifies the number of bytes output in one - line of the C source code. The default is 16. - - <tag/ident/ - This is an optional attribute. When given, the output processor will wrap - the data into an array of unsigned char with the given name. In addition, - three <tt/#define/s are added for <tt/<ident>_COLORS/, - <tt/<ident>_WIDTH/ and <tt/<ident>_HEIGHT/. - -</descrip> - - - -<sect>Bugs/Feedback<p> - -If you have problems using the assembler, if you find any bugs, or if -you're doing something interesting with the assembler, I would be glad to -hear from you. Feel free to contact me by email -(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). - - - -<sect>Copyright<p> - -sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz -and others. For usage of the binaries and/or sources the following conditions -do apply: - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - - - -</article> - - - diff --git a/doc/supervision.sgml b/doc/supervision.sgml deleted file mode 100644 index 504ba5194..000000000 --- a/doc/supervision.sgml +++ /dev/null @@ -1,179 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Watara Supervision specific information for cc65 -<author>Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> -<date>2005-07-17 - -<abstract> -An overview over the Supervision runtime system as it is implemented for the -cc65 C compiler. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This file contains an overview of the Supervision runtime system as it comes -with the cc65 C compiler. It describes the memory layout, Supervision specific header -files, available drivers, and any pitfalls specific to that platform. - -Please note that Supervision specific functions are just mentioned here, they are -described in detail in the separate <htmlurl url="funcref.html" name="function -reference">. Even functions marked as "platform dependent" may be available on -more than one platform. Please see the function reference for more information. - - -<sect>Binary format<p> - -The standard binary output format generated by the linker for the Supervision target -is a 2×16 kbyte machine language program. It is of course -possible to change this behaviour by using one of the different linker configs. - -<sect>Memory layout<p> - -cc65 generated programs with the default setup run with the I/O area enabled, -which gives a usable memory range of $8000 - $FFF9. -More ROM may need additional bankswitching code. - -Special locations: - -<descrip> - <tag/Text screen/ -<!-- The text screen is located at VRAM $4000.--> - No conio support is currently available for the Supervision. - - <tag/Stack/ - The C runtime stack is located at $1FFF and growing downwards. - - <tag/Heap/ - The C heap is located at the end of the program and grows towards the C - runtime stack. - -</descrip><p> - - - -<sect>Platform specific header files<p> - -Programs containing Supervision specific code may use the <tt/supervision.h/ header file. - - -<sect1>Supervision specific functions<p> - -<itemize> -<item>waitvblank -</itemize> - - - -<sect1>Hardware access<p> - -The following pseudo variables declared in the <tt/supervision.inc/ include file do -allow access to hardware located in the address space. - -<descrip> - - <tag><tt/IO/</tag> - The <tt/IO/ defines allow access to the IO chip. - -</descrip><p> - - - -<sect>Loadable drivers<p> - -<sect1>Graphics drivers<p> - -No graphics drivers are currently available for the Supervision. -<!--A TGI driver for the standard graphics mode (160×160 in 4 colors) is -available, but must be statically linked, because no file I/O is available. -See the documentation for the <htmlurl url="co65.html" name="co65 utility"> -for information on how to do that.--> - -<sect1>Extended memory drivers<p> - -No extended memory drivers are currently available for the Supervision. - - -<sect1>Joystick drivers<p> - -No joystick drivers are currently available for the Supervision. -<!--A joystick driver for the standard buttons is available, but must be -statically linked, because no file I/O is available. See the documentation for -the <htmlurl url="co65.html" name="co65 utility"> for information on how to do -that.--> - -<sect1>Mouse drivers<p> - -No mouse drivers are currently available for the Supervision. - - -<sect1>RS232 device drivers<p> - -No communication port drivers are currently available for the Supervision. - - - -<sect>Limitations<p> - -<sect1>Disk I/O<p> - -The existing library for the Supervision doesn't implement C file -I/O. There are even no hacks for the <tt/read()/ and <tt/write()/ routines. - -To be more concrete, this limitation means that you cannot use any of the -following functions (and a few others): - -<itemize> -<item>fclose -<item>fopen -<item>fread -<item>fprintf -<item>fputc -<item>fscanf -<item>fwrite -<item>... -</itemize> - - - -<sect>Other hints<p> - - - -<sect>Bugs/Feedback<p> - -If you have problems using the library, if you find any bugs, or if you're -doing something interesting with it, I would be glad to hear from you. Feel -free to contact me by email (<htmlurl url="mailto:uz@cc65.org" -name="uz@cc65.org">). - - - -<sect>License<p> - -This software is provided 'as-is', without any expressed or implied -warranty. In no event will the authors be held liable for any damages -arising from the use of this software. - -Permission is granted to anyone to use this software for any purpose, -including commercial applications, and to alter it and redistribute it -freely, subject to the following restrictions: - -<enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. -</enum> - -</article> diff --git a/doc/using-make.sgml b/doc/using-make.sgml deleted file mode 100644 index 5affe3b9f..000000000 --- a/doc/using-make.sgml +++ /dev/null @@ -1,156 +0,0 @@ -<!doctype linuxdoc system> - -<article> - -<title>Using GNU Make with cc65 -<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> -<date>2009-06-26 - -<abstract> -How to build your program using the GNU Make utility. -</abstract> - -<!-- Table of contents --> -<toc> - -<!-- Begin the document --> - -<sect>Overview<p> - -This document describes how to build your programs using the cc65 development -tools and the GNU Make utility. - -The cc65 development package doesn't come with a make utility. However this is -no issue because GNU Make works very nicely with cc65. - - - -<sect>What is GNU Make?<p> - -GNU Make is a both very powerful and very popular make utility. It might even -be called the de facto standard for make utilities. For more information see -the GNU Make home page: - -<url url="http://www.gnu.org/software/make/"> - -The cc65 development package is available as binaries for several host systems -and can easily built for quite some additional systems. The very same is true -for GNU Make so a cc65-based project coming with a GNU Make Makefile can easily -be built by any cc65 developer no matter what host system is used. - -Because of the strong alignment of the cc65 compiler with the ISO C standard it -is very well feasible to compile a single C code base both with the cc65 -compiler and other C compilers like for example GCC. GNU Make turns out to be -very well suited to build projects for several target systems using multiple -compilers as it isn't tied to any C compiler. - - - -<sect>A sample Makefile<p> - -This Makefile is a fully functional sample for compiling several C sources -(here <tt/foo.c/ and <tt/bar.c/) and link the resulting object files into an -executable program (here <tt/foobar/): - -<tscreen><verb> -SOURCES = foo.c bar.c - -PROGRAM = foobar - -ifdef CC65_TARGET -CC = $(CC65_HOME)/bin/cl65 -CFLAGS = -t $(CC65_TARGET) --create-dep $(<:.c=.d) -O -LDFLAGS = -t $(CC65_TARGET) -m $(PROGRAM).map -else -CC = gcc -CFLAGS = -MMD -MP -O -LDFLAGS = -Wl,-Map,$(PROGRAM).map -endif - -######################################## - -.SUFFIXES: -.PHONY: all clean -all: $(PROGRAM) - -ifneq ($(MAKECMDGOALS),clean) --include $(SOURCES:.c=.d) -endif - -%.o: %.c - $(CC) -c $(CFLAGS) -o $@ $< - -$(PROGRAM): $(SOURCES:.c=.o) - $(CC) $(LDFLAGS) -o $@ $^ - -clean: - $(RM) $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map -</verb></tscreen> - -<bf/Important:/ When using the sample Makefile above via copy & paste it is -necessary to replace the eight spaces at the beginning of command lines (lines -26, 29 and 32) with a tab character (ASCII code 9). - - -<sect1>Invoking the sample Makefile<p> - -Without any specific configuration the sample Makefile will compile and link -using GCC. In order to rather use cc65 the variable <tt/CC65_TARGET/ needs to be -defined. This may by done as an environment variable or simply as part of the -Makefile. However to quickly switch between compilers and/or cc65 targets it is -best done on the GNU Make command line like this: - -<tscreen><verb> -make CC65_TARGET=c64 -</verb></tscreen> - -The sample Makefile presumes the variable <tt/CC65_HOME/ to point to the -directory cc65 is located in. Again there are several ways to define this -variable but as its value typically won't change often it is best done as an -environment variable. On Windows the cc65 .exe installer package takes care -of creating a <tt/CC65_HOME/ environment variable. - - -<sect1>Understanding the sample Makefile<p> - -Most parts of the sample Makefile follow the guidelines in the -<htmlurl url="http://www.gnu.org/software/make/manual/make.html" name="GNU Make Manual"> -that can be searched online for background information. The automatic generation of -dependency however rather works as described by the GNU Make maintainer Paul D. Smith in -<htmlurl url="http://make.paulandlesley.org/autodep.html#advanced" name="Advanced Auto-Dependencies">. -Fortunately both GCC and cc65 directly support this method in the meantime. - - -<sect1>Invoking the sample Makefile on Windows<p> - -The recommended way to use GNU Make on Windows is to install it as part of a -Cygwin environment. For more information see the Cygwin home page: - -<url url="http://www.cygwin.com/"> - -If however installing Cygwin shouldn't be an option for one or the other reason -then the sample Makefile may be invoked from the Windows Command Prompt (cmd.exe) -by downloading the following programs: - -<itemize> -<item>make.exe: <url url="http://gnuwin32.sourceforge.net/packages/make.htm"> -<item>rm.exe: <url url="http://gnuwin32.sourceforge.net/packages/coreutils.htm"> -</itemize> - - - -<sect>Target-specific Variable Values<p> - -The very limited resources of the cc65 target machines now and then require -manual optimization of the build process by compiling individual source files -with different compiler options. GNU Make offers -<htmlurl url="http://www.gnu.org/software/make/manual/html_node/Target_002dspecific.html" name="Target-specific Variable Values"> -perfectly suited for doing so. For example placing the code of the two modules -<tt/foo/ and <tt/bar/ in the segment <tt/FOOBAR/ can be archived with this -target-specific variable definition: - -<tscreen><verb> -foo.o bar.o: CFLAGS += --code-name FOOBAR -</verb></tscreen> - -</article> diff --git a/doc/vic20.sgml b/doc/vic20.sgml deleted file mode 100644 index 1227ee667..000000000 --- a/doc/vic20.sgml +++ /dev/null @@ -1,269 +0,0 @@ -<!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>