From: Oliver Schmidt Date: Tue, 4 Feb 2014 21:18:58 +0000 (+0100) Subject: Revert "No linuxdoc here. Documenation is to be maintained as HTML in branch 'gh... X-Git-Tag: V2.15~182 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=aa7561ec45fd8f7dbd7ae723b8d9275b48412428;p=cc65 Revert "No linuxdoc here. Documenation is to be maintained as HTML in branch 'gh-pages'." This reverts commit fcea8951f1dc51cce28cabfc9cfec760a341118a. Conflicts: doc/Makefile --- diff --git a/doc/apple2.sgml b/doc/apple2.sgml new file mode 100644 index 000000000..fb6dda7fe --- /dev/null +++ b/doc/apple2.sgml @@ -0,0 +1,544 @@ + + +
+ +Apple ][ specific information for cc65 +<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> +<date>2009-10-07 + +<abstract> +An overview over the Apple ][ runtime system as it is +implemented for the cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Apple ][ runtime system +as it comes with the cc65 C compiler. It describes the memory layout, +Apple ][ specific header files, available drivers, and any +pitfalls specific to that platform. + +Please note that Apple ][ specific functions are just mentioned +here, they are described in detail in the separate <htmlurl url="funcref.html" +name="function reference">. Even functions marked as "platform dependent" may +be available on more than one platform. Please see the function reference for +more information. + + + +<sect>Binary format<p> + +The standard binary file format generated by the linker for the +Apple ][ target is a binary program with a 4 byte DOS 3.3 header +containing the load address and load length. The default load address is +$803. + +<bf/AppleCommander 1.3.5/ or later (available at <url +url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/ +that allows to put binary files with a DOS 3.3 header onto disk images +containing DOS 3.3 as well as ProDOS 8. + +For ProDOS 8 system programs the load address is fixed to $2000 so there +is no need for a header. Thus the linker configuration +<htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> for those programs +omits the DOS 3.3 header. The right AppleCommander option to put system files +without a header on a ProDOS 8 disk image is <tt/-p/. + + +<sect>Memory layout<p> + +In the standard setup, cc65 generated programs use the memory from +$803 to $95FF, so 35.5 KB of RAM are available. + +Special locations: + +<descrip> + + <tag/Stack/ + The C runtime stack is located at HIMEM and grows downwards, regardless of + how your linker config file is setup. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + +While running <tt/main()/ the Language Card bank 2 is enabled for read access. +However while running module constructors/destructors the Language Card is disabled. + +Enabling the Language Card allows to use it as additional memory for cc65 +generated code. However code is never automatically placed there. Rather code +needs to be explicitly placed in the Language Card either per file by compiling +with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma +code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the +cc65 runtime system takes care of actually moving the code into the Language +Card. + +The amount of memory available in the Language Card for generated code depends +on the chosen <htmlurl url="apple2-4.html" name="linker configuration">. + + + +<sect>Linker configurations<p> + +The ld65 linker comes with a builtin config file for the Apple ][, +which is used via <tt/-t apple2/ (and displayed via <tt/--dump-config apple2/). +The apple2 package comes with additional secondary linker config files, which +are used via <tt/-C <configfile>/. + + +<sect1>builtin config file<p> + +Default configuration optimized for a binary program running on ProDOS 8 with +BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card +bank 2 memory from $D400 to $DFFF. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2-dos33.cfg/<p> + +Configuration optimized for a binary program running on DOS 3.3. A plain +vanilla DOS 3.3 doesn't make use of the Language Card at all. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $FFFF (12 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2-system.cfg/<p> + +Configuration for a system program running on ProDOS 8. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $2000 to $BEFF (39.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Fixed ($2000) + + <tag><tt/HEADER:/ Binary file header</tag> + None + +</descrip><p> + + +<sect1><tt/apple2-loader.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/, which is available +in the cc65 User Contributions section. + +A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but +isn't tied to the start address $2000. Thus with the default start +address $800 the main memory area is increased by 6 KB. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2-reboot.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together +with the function <tt/rebootafterexit()/. + +If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather +reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of +the Language Card bank 2 at all. + +This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine! + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $DFFF (4 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + + +<sect>ProDOS 8 system programs<p> + +ProDOS 8 system programs are always loaded to the start address $2000. +For cc65 programs this means that the 6 KB from $800 to $2000 are +by default unused. There are however several options to make use of that memory +range. + + +<sect1>LOADER.SYSTEM<p> + +The easiest (and for really large programs in fact the only) way to have a cc65 +program use the memory from $800 to $2000 is to link it as binary +(as opposed to system) program using the linker configuration +<htmlurl url="apple2-4.html#ss4.4" name="apple2-loader.cfg"> with start address +$800 and load it with <bf/LOADER.SYSTEM - an Apple ][ +ProDOS 8 loader for cc65 programs/. The program then works like a system program +(i.e. quits to the ProDOS dispatcher). + +Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the +program to load under name <program>.SYSTEM as a system program. For +example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. + + +<sect1>Heap<p> + +If the cc65 program can be successfully linked as system program using the linker +configuration <htmlurl url="apple2-4.html#ss4.3" name="apple2-system.cfg"> but +uses the heap either explicitly or implicitly (i.e. by loading a driver) then +the memory from $800 to $2000 can be added to the heap by calling +<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/. + + +<sect1>ProDOS 8 I/O buffers<p> + +ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default +these buffers are allocated by the cc65 runtime system on the heap using +<tt/posix_memalign()/. While this is generally the best solution it means quite +some overhead for (especially rather small) cc65 programs which do open files +but don't make use of the heap otherwise. + +The apple2 package comes with the alternative ProDOS 8 I/O buffer allocation +module <tt/apple2-iobuf-0800.o/ which uses the memory between $800 and +the program start address for the 1 KB I/O buffers. For system programs (with +start address $2000) this results in up to 6 I/O buffers and thus up to 6 +concurrently open files. + +While using <tt/_heapadd()/ as described in the section above together with the +default I/O buffer allocation basically yields the same placement of I/O buffers +in memory the primary benefit of <tt/apple2-iobuf-0800.o/ is a reduction in code +size - and thus program file size - of more than 1400 bytes. + +Using <tt/apple2-iobuf-0800.o/ is as simple as placing it on the linker command +line like this: + +<tscreen><verb> +cl65 -t apple2 -C apple2-system.cfg myprog.c apple2-iobuf-0800.o +</verb></tscreen> + + + +<sect>Platform specific header files<p> + +Programs containing Apple ][ specific code may use the +<tt/apple2.h/ header file. + + +<sect1>Apple ][ specific functions<p> + +The functions listed below are special for the Apple ][. See +the <htmlurl url="funcref.html" name="function reference"> for declaration and +usage. + +<itemize> +<item>_auxtype +<item>_dos_type +<item>_filetype +<item>get_ostype +<item>rebootafterexit +<item>ser_apple2_slot +<item>tgi_apple2_mix +</itemize> + + +<sect1>Hardware access<p> + +There's currently no support for direct hardware access. This does not mean +you cannot do it, it just means that there's no help. + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/a2.lo.tgi (apple2_40_48_16)/</tag> + This driver features a resolution of 40×48 with 16 colors. + + The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The + function clears the corresponding area at the bottom of the screen. + + <tag><tt/a2.hi.tgi (apple2_280_192_8)/</tag> + This driver features a resolution of 280×192 with 8 colors and two + hires pages. Note that programs using this driver will have to be linked + with <tt/--start-addr $4000/ to reserve the first hires page or with + <tt/--start-addr $6000/ to reserve both hires pages. + + The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The + function doesn't clear the corresponding area at the bottom of the screen. + + In memory constrained situations the memory from $803 to $1FFF + can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/ + at the beginning of <tt/main()/. Doing so is beneficial even if the program + doesn't use the the heap explicitly because loading the driver (and in fact + already opening the driver file) uses the heap implicitly. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/a2.auxmem.emd (apple2_auxmem)/</tag> + Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended + 80-Column Text Card. + + Note that this driver doesn't check for the actual existence of the memory + and that it doesn't check for ProDOS 8 RAM disk content! + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/a2.stdjoy.joy (apple2_stdjoy)/</tag> + Supports up to two standard analog joysticks connected to the game port of + the Apple ][. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +<descrip> + + <tag><tt/a2.stdmou.mou (apple2_stdmou)/</tag> + Driver for the AppleMouse II Card. Searches all Apple II slots + for an AppleMouse II Card compatible firmware. The default bounding + box is [0..279,0..191]. + + Programs using this driver will have to be linked with <tt/--start-addr $4000/ + to reserve the first hires page if they are intended to run on an + Apple ][ (in contrast to an Apple //e) because the + AppleMouse II Card firmware writes to the hires page when initializing + on that machine. + + Note that the Apple ][ default mouse callbacks support text + mode only. + +</descrip><p> + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/a2.ssc.ser (apple2_ssc)/</tag> + Driver for the Apple II Super Serial Card. Supports up to 19200 baud, + hardware flow control (RTS/CTS) and interrupt driven receives. Note + that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + + The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to + <tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/ + succeeds for all Apple II slots, but <tt/ser_open()/ fails with + <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot. + +</descrip><p> + + + +<sect>Limitations<p> + + +<sect1>DOS 3.3<p> + +Although the standard binaries generated by the linker for the Apple ][ +generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with +BASIC.SYSTEM) there are some limitations for DOS 3.3: + +<descrip> + + <tag>Disk File I/O</tag> + There's no disk file I/O support. Any attempt to use it yields an error with + <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers + are in general not functional as they depend on disk file I/O. However they + may be converted to statically linked drivers using the co65 object-file + converter. + + <tag/Interrupts/ + There's no <tt/interruptor/ support. Any attempt to use it yields the message + 'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that + <tt/a2.stdmou.mou/ and <tt/a2.ssc.ser/ are not functional as they depend on + interrupts. + +</descrip><p> + + +<sect1>Direct console I/O<p> + +<descrip> + + <tag/Color/ + The Apple ][ has no color text mode. Therefore the functions + <htmlurl url="funcref-205.html" name="textcolor()">, + <htmlurl url="funcref-68.html" name="bgcolor()"> and + <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. + + <tag/Cursor/ + The Apple ][ has no hardware cursor. Therefore the function + <htmlurl url="funcref-88.html" name="cursor()"> has no effect. + +</descrip><p> + + + +<sect>Other hints<p> + + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> +]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Interrupts<p> + +The runtime for the Apple ][ uses routines marked as +<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be +written as simple machine language subroutines and will be called +automatically by the interrupt handler code when they are linked into a +program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl +url="ca65.html" name="assembler manual">. + + +<sect1>DIO<p> + +<descrip> + + <tag/Drive ID/ + The function <htmlurl url="dio-1.html" name="dio_open()"> has the single + parameter <tt/device/ to identify the device to be opened. Therefore an + Apple II slot and drive pair is mapped to that <tt/device/ according + to the formula + + <tscreen> + device = slot + (drive - 1) * 8 + </tscreen> + + so that for example slot 6 drive 2 is mapped to <tt/device/ 14. + + <tag/Sector count/ + The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns + the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8 + disk it simply always returns 280 (which is only correct for a 140 KB disk). + This condition is indicated by the <tt/_oserror/ value 82. + +</descrip><p> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml new file mode 100644 index 000000000..667ae9ec7 --- /dev/null +++ b/doc/apple2enh.sgml @@ -0,0 +1,550 @@ +<!doctype linuxdoc system> + +<article> + +<title>Enhanced Apple //e specific information for cc65 +<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> +<date>2009-10-07 + +<abstract> +An overview over the enhanced Apple //e runtime system as it is +implemented for the cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the enhanced Apple //e runtime system +as it comes with the cc65 C compiler. It describes the memory layout, +enhanced Apple //e specific header files, available drivers, and any +pitfalls specific to that platform. + +Please note that enhanced Apple //e specific functions are just mentioned +here, they are described in detail in the separate <htmlurl url="funcref.html" +name="function reference">. Even functions marked as "platform dependent" may +be available on more than one platform. Please see the function reference for +more information. + + + +<sect>Binary format<p> + +The standard binary file format generated by the linker for the +enhanced Apple //e target is a binary program with a 4 byte DOS 3.3 header +containing the load address and load length. The default load address is +$803. + +<bf/AppleCommander 1.3.5/ or later (available at <url +url="http://applecommander.sourceforge.net/">) includes the option <tt/-cc65/ +that allows to put binary files with a DOS 3.3 header onto disk images +containing DOS 3.3 as well as ProDOS 8. + +For ProDOS 8 system programs the load address is fixed to $2000 so there +is no need for a header. Thus the linker configuration +<htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> for those programs +omits the DOS 3.3 header. The right AppleCommander option to put system files +without a header on a ProDOS 8 disk image is <tt/-p/. + + +<sect>Memory layout<p> + +In the standard setup, cc65 generated programs use the memory from +$803 to $95FF, so 35.5 KB of RAM are available. + +Special locations: + +<descrip> + + <tag/Stack/ + The C runtime stack is located at HIMEM and grows downwards, regardless of + how your linker config file is setup. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + +While running <tt/main()/ the Language Card bank 2 is enabled for read access. +However while running module constructors/destructors the Language Card is disabled. + +Enabling the Language Card allows to use it as additional memory for cc65 +generated code. However code is never automatically placed there. Rather code +needs to be explicitly placed in the Language Card either per file by compiling +with <tt/--code-name HIGHCODE/ or per function by enclosing in <tt/#pragma +code-name (push, "HIGHCODE")/ and <tt/#pragma code-name (pop)/. In either case the +cc65 runtime system takes care of actually moving the code into the Language +Card. + +The amount of memory available in the Language Card for generated code depends +on the chosen <htmlurl url="apple2enh-4.html" name="linker configuration">. + + + +<sect>Linker configurations<p> + +The ld65 linker comes with a builtin config file for the enhanced Apple //e, +which is used via <tt/-t apple2enh/ (and displayed via <tt/--dump-config apple2enh/). +The apple2enh package comes with additional secondary linker config files, which +are used via <tt/-C <configfile>/. + + +<sect1>builtin config file<p> + +Default configuration optimized for a binary program running on ProDOS 8 with +BASIC.SYSTEM. A plain vanilla ProDOS 8 doesn't actually use the Language Card +bank 2 memory from $D400 to $DFFF. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-dos33.cfg/<p> + +Configuration optimized for a binary program running on DOS 3.3. A plain +vanilla DOS 3.3 doesn't make use of the Language Card at all. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $803 to $95FF (35.5 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $FFFF (12 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $803) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-system.cfg/<p> + +Configuration for a system program running on ProDOS 8. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $2000 to $BEFF (39.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Fixed ($2000) + + <tag><tt/HEADER:/ Binary file header</tag> + None + +</descrip><p> + + +<sect1><tt/apple2enh-loader.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/, which is available +in the cc65 User Contributions section. + +A program loaded by LOADER.SYSTEM works like a ProDOS 8 system program but +isn't tied to the start address $2000. Thus with the default start +address $800 the main memory area is increased by 6 KB. + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D400 to $DFFF (3 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + +<sect1><tt/apple2enh-reboot.cfg/<p> + +Configuration optimized for a binary program running on ProDOS 8 without +BASIC.SYSTEM. Intended to be used with <bf/LOADER.SYSTEM - an +Apple ][ ProDOS 8 loader for cc65 programs/ (see above) together +with the function <tt/rebootafterexit()/. + +If a ProDOS 8 system program doesn't quit to the ProDOS 8 dispatcher but rather +reboots the machine after exit then a plain vanilla ProDOS 8 doesn't make use of +the Language Card bank 2 at all. + +This setup makes nearly 50 KB available to a cc65 program - on a 64 KB machine! + +<descrip> + + <tag><tt/RAM:/ Main memory area</tag> + From $800 to $BEFF (45.75 KB) + + <tag><tt/LC:/ Language Card memory area</tag> + From $D000 to $DFFF (4 KB) + + <tag><tt/STARTADDRESS:/ Program start address</tag> + Variable (default: $800) + + <tag><tt/HEADER:/ Binary file header</tag> + DOS 3.3 header (address and length) + +</descrip><p> + + + +<sect>ProDOS 8 system programs<p> + +ProDOS 8 system programs are always loaded to the start address $2000. +For cc65 programs this means that the 6 KB from $800 to $2000 are +by default unused. There are however several options to make use of that memory +range. + + +<sect1>LOADER.SYSTEM<p> + +The easiest (and for really large programs in fact the only) way to have a cc65 +program use the memory from $800 to $2000 is to link it as binary +(as opposed to system) program using the linker configuration +<htmlurl url="apple2enh-4.html#ss4.4" name="apple2enh-loader.cfg"> with start address +$800 and load it with <bf/LOADER.SYSTEM - an Apple ][ +ProDOS 8 loader for cc65 programs/. The program then works like a system program +(i.e. quits to the ProDOS dispatcher). + +Using LOADER.SYSTEM is as simple as copying it to the ProDOS 8 directory of the +program to load under name <program>.SYSTEM as a system program. For +example the program <tt/MYPROG/ is loaded by <tt/MYPROG.SYSTEM/. + + +<sect1>Heap<p> + +If the cc65 program can be successfully linked as system program using the linker +configuration <htmlurl url="apple2enh-4.html#ss4.3" name="apple2enh-system.cfg"> but +uses the heap either explicitly or implicitly (i.e. by loading a driver) then +the memory from $800 to $2000 can be added to the heap by calling +<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/. + + +<sect1>ProDOS 8 I/O buffers<p> + +ProDOS 8 requires for every open file a page-aligned 1 KB I/O buffer. By default +these buffers are allocated by the cc65 runtime system on the heap using +<tt/posix_memalign()/. While this is generally the best solution it means quite +some overhead for (especially rather small) cc65 programs which do open files +but don't make use of the heap otherwise. + +The apple2enh package comes with the alternative ProDOS 8 I/O buffer allocation +module <tt/apple2enh-iobuf-0800.o/ which uses the memory between $800 and +the program start address for the 1 KB I/O buffers. For system programs (with +start address $2000) this results in up to 6 I/O buffers and thus up to 6 +concurrently open files. + +While using <tt/_heapadd()/ as described in the section above together with the +default I/O buffer allocation basically yields the same placement of I/O buffers +in memory the primary benefit of <tt/apple2enh-iobuf-0800.o/ is a reduction in code +size - and thus program file size - of more than 1400 bytes. + +Using <tt/apple2enh-iobuf-0800.o/ is as simple as placing it on the linker command +line like this: + +<tscreen><verb> +cl65 -t apple2enh -C apple2enh-system.cfg myprog.c apple2enh-iobuf-0800.o +</verb></tscreen> + + + +<sect>Platform specific header files<p> + +Programs containing enhanced Apple //e specific code may use the +<tt/apple2enh.h/ header file. + + +<sect1>Enhanced Apple //e specific functions<p> + +The functions listed below are special for the enhanced Apple //e. See +the <htmlurl url="funcref.html" name="function reference"> for declaration and +usage. + +<itemize> +<item>_auxtype +<item>_dos_type +<item>_filetype +<item>get_ostype +<item>rebootafterexit +<item>ser_apple2_slot +<item>textframe +<item>textframexy +<item>tgi_apple2_mix +<item>videomode +</itemize> + + +<sect1>Hardware access<p> + +There's currently no support for direct hardware access. This does not mean +you cannot do it, it just means that there's no help. + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/a2e.lo.tgi (apple2_40_48_16)/</tag> + This driver features a resolution of 40×48 with 16 colors. + + The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The + function clears the corresponding area at the bottom of the screen. + + <tag><tt/a2e.hi.tgi (apple2_280_192_8)/</tag> + This driver features a resolution of 280×192 with 8 colors and two + hires pages. Note that programs using this driver will have to be linked + with <tt/--start-addr $4000/ to reserve the first hires page or with + <tt/--start-addr $6000/ to reserve both hires pages. + + Note that the second hires page is only available if the text display is not in + 80 column mode. This can be asserted by calling <tt/videomode (VIDEOMODE_40COL);/ + before installing the driver. + + The function <tt/tgi_apple2_mix()/ allows to activate 4 lines of text. The + function doesn't clear the corresponding area at the bottom of the screen. + + In memory constrained situations the memory from $803 to $1FFF + can be made available to a program by calling <tt/_heapadd ((void *) 0x0803, 0x17FD);/ + at the beginning of <tt/main()/. Doing so is beneficial even if the program + doesn't use the the heap explicitly because loading the driver (and in fact + already opening the driver file) uses the heap implicitly. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/a2e.auxmem.emd (apple2_auxmem)/</tag> + Gives access to 47.5 KB RAM (190 pages of 256 bytes each) on an Extended + 80-Column Text Card. + + Note that this driver doesn't check for the actual existence of the memory + and that it doesn't check for ProDOS 8 RAM disk content! + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/a2e.stdjoy.joy (apple2_stdjoy)/</tag> + Supports up to two standard analog joysticks connected to the game port of + the enhanced Apple //e. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +<descrip> + + <tag><tt/a2e.stdmou.mou (apple2_stdmou)/</tag> + Driver for the AppleMouse II Card. Searches all Apple II slots + for an AppleMouse II Card compatible firmware. The default bounding + box is [0..279,0..191]. + + Note that the enhanced Apple //e default mouse callbacks support + text mode only. + +</descrip><p> + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/a2e.ssc.ser (apple2_ssc)/</tag> + Driver for the Apple II Super Serial Card. Supports up to 19200 baud, + hardware flow control (RTS/CTS) and interrupt driven receives. Note + that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + + The driver defaults to slot 2. Call <tt/ser_apple2_slot()/ prior to + <tt/ser_open()/ in order to select a different slot. <tt/ser_apple2_slot()/ + succeeds for all Apple II slots, but <tt/ser_open()/ fails with + <tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot. + +</descrip><p> + + + +<sect>Limitations<p> + + +<sect1>DOS 3.3<p> + +Although the standard binaries generated by the linker for the enhanced Apple //e +generally run both on DOS 3.3 (with Applesoft BASIC) and on ProDOS 8 (with +BASIC.SYSTEM) there are some limitations for DOS 3.3: + +<descrip> + + <tag>Disk File I/O</tag> + There's no disk file I/O support. Any attempt to use it yields an error with + <tt/errno/ set to <tt/ENOSYS/. This implicitly means that loadable drivers + are in general not functional as they depend on disk file I/O. However they + may be converted to statically linked drivers using the co65 object-file + converter. + + <tag/Interrupts/ + There's no <tt/interruptor/ support. Any attempt to use it yields the message + 'Failed to alloc interrupt' on program startup. This implicitly means that + <tt/a2e.stdmou.mou/ and <tt/a2e.ssc.ser/ are not functional as they depend on + interrupts. + +</descrip><p> + + +<sect1>Direct console I/O<p> + +<descrip> + + <tag/Color/ + The enhanced Apple //e has no color text mode. Therefore the functions + <htmlurl url="funcref-205.html" name="textcolor()">, + <htmlurl url="funcref-68.html" name="bgcolor()"> and + <htmlurl url="funcref-69.html" name="bordercolor()"> have no effect. + + <tag/Cursor/ + The enhanced Apple //e has no hardware cursor. Therefore the function + <htmlurl url="funcref-88.html" name="cursor()"> has no effect. + +</descrip><p> + + + +<sect>Other hints<p> + + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/ after BLOAD. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> +]CALL2051:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Function keys<p> + +These are defined to be OpenApple + number key. + + +<sect1>Interrupts<p> + +The runtime for the enhanced Apple //e uses routines marked as +<tt/.INTERRUPTOR/ for ProDOS 8 interrupt handlers. Such routines must be +written as simple machine language subroutines and will be called +automatically by the interrupt handler code when they are linked into a +program. See the discussion of the <tt/.CONDES/ feature in the <htmlurl +url="ca65.html" name="assembler manual">. + + +<sect1>DIO<p> + +<descrip> + + <tag/Drive ID/ + The function <htmlurl url="dio-1.html" name="dio_open()"> has the single + parameter <tt/device/ to identify the device to be opened. Therefore an + Apple II slot and drive pair is mapped to that <tt/drive_id/ according + to the formula + + <tscreen> + device = slot + (drive - 1) * 8 + </tscreen> + + so that for example slot 6 drive 2 is mapped to <tt/device/ 14. + + <tag/Sector count/ + The function <htmlurl url="dio-3.html" name="dio_query_sectcount()"> returns + the correct sector count for all ProDOS 8 disks. However for any non-ProDOS 8 + disk it simply always returns 280 (which is only correct for a 140 KB disk). + This condition is indicated by the <tt/_oserror/ value 82. + +</descrip><p> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/ar65.sgml b/doc/ar65.sgml new file mode 100644 index 000000000..d4e19a5c5 --- /dev/null +++ b/doc/ar65.sgml @@ -0,0 +1,156 @@ +<!doctype linuxdoc system> + +<article> + +<title>ar65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>19.07.2000 + +<abstract> +ar65 is an archiver for object files generated by ca65. It allows to create +archives, add or remove modules from archives, and to extract modules from +existing archives. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + + +ar65 is a replacement for the libr65 archiver that was part of the cc65 C +compiler suite developed by John R. Dunning. libr65 had some problems and +the copyright does not permit some things which I wanted to be possible, +so I decided to write a completely new assembler/linker/archiver suite +for the cc65 compiler. ar65 is part of this suite. + +<sect>Usage<p> + + +The archiver is called as follows: + +<tscreen><verb> + Usage: ar65 <operation> lib file|module ... + Operation is one of: + a Add modules + d Delete modules + l List library contents + x Extract modules + V Print the archiver version +</verb></tscreen> + +You may add modules to a library using the `a' command. If the library +does not exist, it is created (and a warning message is printed which you +may ignore if creation of the library was your intention). You may +specify any number of modules on the command line following the library. + +If a module with the same name exists in the library, it is replaced by +the new one. The archiver prints a warning, if the module in the library +has a newer timestamp than the one to add. + +Here's an example: + +<tscreen><verb> + ar65 a mysubs.lib sub1.o sub2.o +</verb></tscreen> + +This will add two modules to the library `mysubs.lib' creating the +library if necessary. If the library contains modules named sub1.o or +sub2.o, they are replaced by the new ones. + +Modules names in the library are stored without the path, so, using + +<tscreen><verb> + ar65 a mysubs.lib ofiles/sub1.o ofiles/sub2.o +</verb></tscreen> + +will add two modules named `sub1.o' and `sub2.o' to the library. + +Deleting modules from a library is done with the `d' command. You may not +give a path when naming the modules. + +Example: + +<tscreen><verb> + ar65 d mysubs.lib sub1.o +</verb></tscreen> + +This will delete the module named `sub1.o' from the library, printing an +error if the library does not contain that module. + + +The `l' command prints a list of all modules in the library. Any module +names on the command line are ignored. + +Example: + +<tscreen><verb> + ar65 l mysubs.lib +</verb></tscreen> + + +Using the `x' command, you may extract modules from the library. The +modules named on the command line are extracted from the library and put +into the current directory. + +Note: Because of the indexing done by the archiver, the modules may have +a changed binary layout, that is, a binary compare with the old module +(before importing it into the library) may yield differences. The +extracted modules are accepted by the linker and archiver, however, so +this is not a problem. + +Example for extracting a module from the library: + +<tscreen><verb> + ar65 x mysubs.lib sub1.o +</verb></tscreen> + + +The `V' command prints the version number of the assembler. If you send +any suggestions or bugfixes, please include your version number. + +In addition to these operations, the archiver will check for, and warn +about duplicate external symbols in the library, every time when an +operation does update the library. This is only a warning, the linker +will ignore one of the duplicate symbols (which one is unspecified). + + +<sect>Bugs/Feedback<p> + +If you have problems using the archiver, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ar65 (and all cc65 binutils) are (C) Copyright 1998-2000 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following conditions +do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/atari.sgml b/doc/atari.sgml new file mode 100644 index 000000000..9fe75ec2a --- /dev/null +++ b/doc/atari.sgml @@ -0,0 +1,590 @@ +<!doctype linuxdoc system> + +<article> + +<title>Atari specific information for cc65 +<author>Shawn Jefferson, <htmlurl +url="mailto:shawnjefferson@24fightingchickens.com" +name="shawnjefferson@24fightingchickens.com"> and +Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org"> +<date>03-Jan-2006 + +<abstract> +An overview over the Atari runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Atari runtime system as it comes +with the cc65 C compiler. It describes the memory layout, Atari specific +header files, available drivers, and any pitfalls specific to that +platform. + +Please note that Atari specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the +Atari target is a machine language program with a standard executable +header (FF FF <2 byte start address> <2 bytes end address> +[program bytes]). These values are calculated in the crt0.s +file from the __STARTUP_LOAD__ and __ZPSAVE_LOAD__ values, so keep +this in mind if you create a custom linker config file and start +moving segments around (see section +<ref name="Reserving a memory area inside the program" id="memhole">). +You can override this behaviour by creating your own crt0.s file and +linking it into your program. A run vector is added to the end of the +file ($02E0 <run vector>) and is calculated using +__STARTUP_LOAD__ in crt0.s. + + +<sect>Memory layout<p> + +The default linker script assumes that the BASIC ROM is disabled (or +the BASIC cartridge unplugged). This gives a usable memory range from +$2E00 - $BC1F. The library startup code examines the +current memory configuration, which depends on the size of the +installed memory and cartridges present, by inspecting the value in +the MEMTOP ($2E5) variable. Then the initial stack pointer, +which indicates the upper bound of memory used, is adjusted. The +default load address of $2E00 was chosen to accommodate having +a DOS loaded and a driver that resides in low memory such as the 850 +R: handler. You can override this behaviour by creating a custom +linker config file or by using the "--start-addr" cl65 command line +argument or the "--start-addr" or "-S" ld65 command line arguments. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen depends on the installed memory size and cartridges + and can be obtained from the SAVMSC variable ($58). + + <tag/Stack/ + The C runtime stack is located at MEMTOP and grows downwards, + regardless of how your linker config file is setup. This + accommodates the different memory configurations of the Atari + machines, as well as having a cartridge installed. You can override + this behaviour by writing your own crt0.s file and linking it to + your program (see also <ref name="Final note" + id="memhole_final_note">). + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Atari specific code may use the <tt/atari.h/ +header file. + + +<sect1>Atari specific functions<p> + +The functions and global variable listed below are special for the Atari. +See the <htmlurl url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>get_ostype +<item>get_tv +<item>_dos_type +<item>_gtia_mkcolor +<item>_getcolor +<item>_getdefdev +<item>_graphics +<item>_rest_vecs +<item>_save_vecs +<item>_scroll +<item>_setcolor +<item>_setcolor_low +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/atari.h/ header +file do allow access to hardware located in the address space. Some +variables are structures, accessing the struct fields will access the +chip registers. + +<descrip> + + <tag><tt/GTIA_READ/ and <tt/GTIA_WRITE/</tag> + The <tt/GTIA_READ/ structure allows read access to the GTIA. The + <tt/GTIA_WRITE/ structure allows write access to the GTIA. + See the <tt/_gtia.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/POKEY_READ/ and <tt/POKEY_WRITE/</tag> + The <tt/POKEY_READ/ structure allows read access to the POKEY. The + <tt/POKEY_WRITE/ structure allows write access to the POKEY. + See the <tt/_pokey.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/ANTIC/</tag> + The <tt/ANTIC/ structure allows read access to the ANTIC. + See the <tt/_antic.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/PIA/</tag> + The <tt/PIA/ structure allows read access to the PIA 6520. + See the <tt/_pia.h/ header file located in the include directory + for the declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/atari10.tgi (atari_10)/</tag> + + <tag><tt/atr10p2.tgi (atari_10p2)/</tag> + + <tag><tt/atari11.tgi (atari_11)/</tag> + + <tag><tt/atari14.tgi (atari_14)/</tag> + + <tag><tt/atari15.tgi (atari_15)/</tag> + + <tag><tt/atr15p2.tgi (atari_15p2)/</tag> + + <tag><tt/atari3.tgi (atari_3)/</tag> + + <tag><tt/atari4.tgi (atari_4)/</tag> + + <tag><tt/atari5.tgi (atari_5)/</tag> + + <tag><tt/atari6.tgi (atari_6)/</tag> + + <tag><tt/atari7.tgi (atari_7)/</tag> + + <tag><tt/atari8.tgi (atari_8)/</tag> + + <tag><tt/atr8p2.tgi (atari_8p2)/</tag> + + <tag><tt/atari9.tgi (atari_9)/</tag> + + <tag><tt/atr9p2.tgi (atari_9p2)/</tag> + +</descrip><p> + +Many graphics modes require more memory than the text screen which is +in effect when the program starts up. Therefore the programmer has to +tell the program beforehand the memory requirements of the graphics +modes the program intends to use. +This can be done by using the __RESERVED_MEMORY__ linker config +variable. The number specified there describes the number of bytes to +subtract from the top of available memory as seen from the runtime +library. This memory is then used by the screen buffer. + +The numbers for the different graphics modes presented below should +only be seen as a rule of thumb. Since the screen buffer memory needs +to start at specific boundaries, the numbers depend on the current top +of available memory. +The following numbers were determined by a BASIC program. + +<table> +<tabular ca="rr"> +graphics mode|reserved memory@<hline> +0|1@ +1|1@ +2|1@ +3|1@ +4|1@ +5|182@ +6|1182@ +7|3198@ +8|7120@ +9|7146@ +10|7146@ +11|7146@ +12|162@ +13|1@ +14|3278@ +15|7120@ +16|1@ +17|1@ +18|1@ +19|1@ +20|1@ +21|184@ +22|1192@ +23|3208@ +24|7146@ +25|7146@ +26|7146@ +27|7146@ +28|162@ +29|1@ +30|3304@ +31|7146 +</tabular> +<caption>reserved memory required for different graphics modes +</table> + +The values of "1" are needed because the graphics command crashes if +it doesn't have at least one byte available. This seems to be a bug of +the Atari ROM code. + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/atr130xe.emd (atari_130xe)/</tag> + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/ataristd.joy (atari_stdjoy)/</tag> + Supports up to four standard joysticks connected to the joystick ports of + the Atari. + + <tag><tt/atarim8.joy (atari_multijoy)/</tag> + Supports up to eight standard joysticks connected to a MultiJoy adapter. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). There is a static driver you can use. + + +<sect1>RS232 device drivers<p> + +Currently there are no RS232 loadable drivers available for the Atari +platform. There is a static driver you can use. + + +<sect>Limitations<p> + + +<sect>DIO implementation<label id="dio"><p> + +The Atari supports disk drives with either 128 or 256 byte sectors. +The first three sectors of any disk are always 128 bytes long though. This is +because the system can only boot from 128 bytes sectors. + +Therefore the DIO read and write functions transfer only 128 bytes +for sectors 1 to 3, regardless of the type of diskette. + + +<sect>CONIO implementation<label id="conio"><p> + +The console I/O is speed optimized therefore support for XEP80 hardware +or f80.com software is missing. Of course you may use stdio.h functions. + + +<sect>Other hints<p> + + +<sect1>Function keys<p> + +Function keys are mapped to Atari + number key. + + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/ when DOS supports it. + +<enum> +<item>Arguments are separated by spaces. +<item>Leading and trailing spaces around an argument are ignored. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 16 arguments (including the program name) are + supported. +</enum> + + +<sect1>Interrupts<p> + +The runtime for the Atari uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the VBI handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + +<sect1>Reserving a memory area inside a program<label id="memhole"><p> + +The Atari 130XE maps its additional memory into CPU memory in 16K +chunks at address $4000 to $7FFF. One might want to +prevent this memory area from being used by cc65. Other reasons to +prevent the use of some memory area could be to reserve space for the +buffers for display lists and screen memory. +<p> +The Atari executable format allows holes inside a program, e.g. one +part loads into $2E00 to $3FFF, going below the reserved +memory area (assuming a reserved area from $4000 to +$7FFF), and another part loads into $8000 to +$BC1F. +<p> +Each load chunk of the executable starts with a 4 byte header which +defines its load address and size. In the following linker scripts +these headers are named HEADER and SECHDR (for the MEMORY layout), and +accordingly NEXEHDR and CHKHDR (for the SEGMENTS layout). +<p> +<sect2>Low code and high data example<p> +Goal: Create an executable with 2 load chunks which doesn't use the +memory area from $4000 to $7FFF. The CODE segment of +the program should go below $4000 and the DATA and RODATA +segments should go above $7FFF. +<p> +The main problem is that the EXE header generated by the cc65 runtime +lib is wrong. It defines a single load chunk with the sizes/addresses +of the STARTUP, LOWCODE, INIT, CODE, RODATA, and DATA segments (the whole user +program). +<p> +The contents of the EXE header come from the EXEHDR segment, which is +defined in crt0.s. This cannot be changed without modifying and +recompiling the cc65 atari runtime lib. Therefore the original EXE +header must be discarded. It will be replaced by a user created +one. The discarding is done by assigning the EXEHDR segment to the +BANK memory area. The BANK memory area is discarded in the new linker +script (written to file ""). +<p> +The user needs to create a customized linker config file which adds +new memory areas and segments to hold the new EXE header and the +header data for the second load chunk. Also an assembly source file +needs to be created which defines the contents of the new EXE header +and the second load chunk header. +<p> +<p> +This is an example of a modified cc65 Atari linker configuration file +(split.cfg): +<tscreen><verb> +SYMBOLS { + __STACKSIZE__ = $800; # 2K stack + __RESERVED_MEMORY__: value = $0000, weak = yes; +} +FEATURES { + STARTADDRESS: default = $2E00; +} +MEMORY { + ZP: start = $82, size = $7E, type = rw, define = yes; + + HEADER: start = $0000, size = $6, file = %O; # first load chunk + RAMLO: start = %S, size = $4000 - %S, file = %O; + + BANK: start = $4000, size = $4000, file = ""; + + SECHDR: start = $0000, size = $4, file = %O; # second load chunk + RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F +} +SEGMENTS { + EXEHDR: load = BANK, type = ro; + + NEXEHDR: load = HEADER, type = ro; # first load chunk + STARTUP: load = RAMLO, type = ro, define = yes; + LOWCODE: load = RAMLO, type = ro, define = yes, optional = yes; + INIT: load = RAMLO, type = ro, optional = yes; + CODE: load = RAMLO, type = ro, define = yes; + + CHKHDR: load = SECHDR, type = ro; # second load chunk + RODATA: load = RAM, type = ro, define = yes; + DATA: load = RAM, type = rw, define = yes; + BSS: load = RAM, type = bss, define = yes; + ZPSAVE: load = RAM, type = bss, define = yes; + + ZEROPAGE: load = ZP, type = zp; + AUTOSTRT: load = RAM, type = ro; # defines program entry point +} +FEATURES { + CONDES: segment = RODATA, + type = constructor, + label = __CONSTRUCTOR_TABLE__, + count = __CONSTRUCTOR_COUNT__; + CONDES: segment = RODATA, + type = destructor, + label = __DESTRUCTOR_TABLE__, + count = __DESTRUCTOR_COUNT__; +} +</verb></tscreen> +<p> + +A new memory area BANK was added which describes the reserved area. +It gets loaded with the contents of the old EXEHDR segment. But the +memory area isn't written to the output file. This way the contents of +the EXEHDR segment get discarded. +<p> +The newly added NEXEHDR segment defines the correct EXE header. It +puts the STARTUP, LOWCODE, INIT, and CODE segments, which are the +segments containing only code, into load chunk #1 (RAMLO memory area). +<p> +The header for the second load chunk comes from the new CHKHDR +segment. It puts the RODATA, DATA, BSS, and ZPSAVE segments into load +chunk #2 (RAM memory area). +<p> +<p> +The contents of the new NEXEHDR and CHKHDR segments come from this +file (split.s): +<tscreen><verb> + .import __CODE_LOAD__, __BSS_LOAD__, __CODE_SIZE__ + .import __DATA_LOAD__, __RODATA_LOAD__, __STARTUP_LOAD__ + + .segment "NEXEHDR" + .word $FFFF + .word __STARTUP_LOAD__ + .word __CODE_LOAD__ + __CODE_SIZE__ - 1 + + .segment "CHKHDR" + .word __RODATA_LOAD__ + .word __BSS_LOAD__ - 1 +</verb></tscreen> +<p> +Compile with +<tscreen><verb> +cl65 -t atari -C split.cfg -o prog.com prog.c split.s +</verb></tscreen> + +<sect2>Low data and high code example<p> + + +Goal: Put RODATA and DATA into low memory and STARTUP, LOWCODE, INIT, +CODE, BSS, ZPSAVE into high memory (split2.cfg): + +<tscreen><verb> +SYMBOLS { + __STACKSIZE__ = $800; # 2K stack + __RESERVED_MEMORY__: value = $0000, weak = yes; +} +FEATURES { + STARTADDRESS: default = $2E00; +} +MEMORY { + ZP: start = $82, size = $7E, type = rw, define = yes; + + HEADER: start = $0000, size = $6, file = %O; # first load chunk + RAMLO: start = %S, size = $4000 - %S, file = %O; + + BANK: start = $4000, size = $4000, file = ""; + + SECHDR: start = $0000, size = $4, file = %O; # second load chunk + RAM: start = $8000, size = $3C20, file = %O; # $3C20: matches upper bound $BC1F +} +SEGMENTS { + EXEHDR: load = BANK, type = ro; # discarded old EXE header + + NEXEHDR: load = HEADER, type = ro; # first load chunk + RODATA: load = RAMLO, type = ro, define = yes; + DATA: load = RAMLO, type = rw, define = yes; + + CHKHDR: load = SECHDR, type = ro; # second load chunk + STARTUP: load = RAM, type = ro, define = yes; + INIT: load = RAM, type = ro, optional = yes; + CODE: load = RAM, type = ro, define = yes; + ZPSAVE: load = RAM, type = bss, define = yes; + BSS: load = RAM, type = bss, define = yes; + + ZEROPAGE: load = ZP, type = zp; + AUTOSTRT: load = RAM, type = ro; # defines program entry point +} +FEATURES { + CONDES: segment = RODATA, + type = constructor, + label = __CONSTRUCTOR_TABLE__, + count = __CONSTRUCTOR_COUNT__; + CONDES: segment = RODATA, + type = destructor, + label = __DESTRUCTOR_TABLE__, + count = __DESTRUCTOR_COUNT__; +} +</verb></tscreen> + +New contents for NEXEHDR and CHKHDR are needed (split2.s): +<tscreen><verb> + .import __STARTUP_LOAD__, __ZPSAVE_LOAD__, __DATA_SIZE__ + .import __DATA_LOAD__, __RODATA_LOAD__ + + .segment "NEXEHDR" + .word $FFFF + .word __RODATA_LOAD__ + .word __DATA_LOAD__ + __DATA_SIZE__ - 1 + + .segment "CHKHDR" + .word __STARTUP_LOAD__ + .word __ZPSAVE_LOAD__ - 1 +</verb></tscreen> + +Compile with +<tscreen><verb> +cl65 -t atari -C split2.cfg -o prog.com prog.c split2.s +</verb></tscreen> + +<sect2>Final note<label id="memhole_final_note"><p> + +There are two other memory areas which don't appear directly in the +linker script. They are the stack and the heap. + +The cc65 runtime lib places the stack location at the end of available +memory. This is dynamically set from the MEMTOP system variable at +startup. The heap is located in the area between the end of the BSS +segment and the top of the stack as defined by __STACKSIZE__. + +If BSS and/or the stack shouldn't stay at the end of the program, +some parts of the cc65 runtime lib need to be replaced/modified. + +common/_heap.s defines the location of the heap and atari/crt0.s +defines the location of the stack by initializing sp. + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org"> or <htmlurl url="mailto:chris@groessler.org" +name="chris@groessler.org"> ). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/atmos.sgml b/doc/atmos.sgml new file mode 100644 index 000000000..8e24c92a1 --- /dev/null +++ b/doc/atmos.sgml @@ -0,0 +1,260 @@ +<!doctype linuxdoc system> + +<article> + +<title>Oric Atmos specific information for cc65 +<author>Ullrich von Bassewitz <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"><newline> +Stefan A. Haubenthal <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"><newline> +<url url="mailto:greg.king5@verizon.net" name="Greg King"> +<date>2013-01-08 + +<abstract> +An overview over the Atmos runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Atmos runtime system as it comes with the +cc65 C compiler. It describes the memory layout, Atmos specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that Atmos specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Atmos target +is a machine language program with a 17 byte tape header including a cc65 tag. +The standard load and autostart address is $500. + + +<sect>Memory layout<p> + +In the standard setup, cc65 generated programs use the memory from +$500 to $9800, so nearly 37K of memory (including the stack) is +available. ROM calls are possible without further precautions. + +Special locations: + +<descrip> + <tag/Stack/ + The C runtime stack is located at $97FF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Atmos specific code may use the <tt/atmos.h/ header file. + + +<sect1>Atmos specific functions<p> + +The functions listed below are special for the Atmos. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>atmos_load +<item>atmos_save +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/atmos.h/ header file do allow +access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/VIA/</tag> + Access to the VIA (versatile interface adapter) chip is available via the + <tt/VIA/ variable. The structure behind this variable is explained in <tt/_6522.h/. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +<em>Note:</em> Since the Atmos doesn't have working disk I/O +(see <ref id="limitations" name="section "Limitations"">), the +available drivers cannot be loaded at runtime (so the term "loadable drivers" +is somewhat misleading). Instead, the drivers have to be statically linked. While +this may seem overhead, it has two advantages: + +<enum> +<item>The interface is identical to the one used for other platforms + and to the one for the Atmos once it has disk I/O. +<item>Once disk I/O is available, existing code can be changed to load drivers + at runtime with almost no effort. +</enum> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/atmos-228-200-3.tgi (atmos_228_200_3)/</tag> + This driver was written by Greg King and Stefan Haubenthal. + It features a resolution of 228×200 with a palette of two colors that + can be chosen from the Atmos's eight colors. The driver supports a third + palette-"color" that actually "flips" the pixel (it becomes the other color) + that is on the screen under the graphics cursor. + + <tag><tt/atmos-240-200-2.tgi (atmos_240_200_2)/</tag> + This driver was written by Stefan Haubenthal and Greg King. + It features a resolution of 240×200 with black and white colors. + It is the default graphics driver for the Atmos. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Atmos. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/atmos-pase.joy (atmos_pase)/</tag> + Supports two standard joysticks connected to the P.A.S.E. interface of the Atmos. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Atmos. + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/atmos-acia.ser (atmos_acia)/</tag> + Driver for the Telestrat integrated serial controller and the Atmos with a + serial add-on. + Note that because of the peculiarities of the 6551 chip together with the + use of the NMI, transmits are not interrupt driven, and the transceiver + blocks if the receiver asserts flow control because of a full buffer. + +</descrip><p> + + + +<sect>Limitations<label id="limitations"><p> + +<sect1>Disk I/O<p> + +The existing library for the Atmos doesn't implement C file +I/O. There is one hack for the <tt/write()/ routine in +place, which will make functions work that write to <tt/stdout/ +(like <tt/printf()/). However, this function has some shortcomings which +won't be fixed, because it's going to be replaced anyway. + +To be more concrete, this limitation means that you cannot use any of the +following functions (and a few others): + +<itemize> +<item>fclose +<item>fopen +<item>fread +<item>fprintf +<item>fputc +<item>fscanf +<item>fwrite +<item>... +</itemize> + + + +<sect>Other hints<p> + +<sect1>Function keys<p> + +These are defined to be FUNCT + number key. + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + CALL#500:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Interrupts<p> + +The runtime for the Atmos uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/c128.sgml b/doc/c128.sgml new file mode 100644 index 000000000..37cdd25f8 --- /dev/null +++ b/doc/c128.sgml @@ -0,0 +1,356 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 128 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-14 + +<abstract> +An overview over the C128 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the C128 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, C128 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that C128 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the C128 target +is a machine language program with a one line BASIC stub, which calls the +machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and the +kernal ROM enabled. Note that this is a non standard memory layout, and that +there is no "memory configuration index" for this layout. This means that +special care has to be taken when changing the configuration, or calling any +code that does this. The memory configuration register at $FF00 should +be saved and restored instead of relying on the memory configuration index +stored in the zero page. + +The setup gives a usable memory range of $1C00 - $BFFF. Having +just the kernal ROM mapped in means, that kernal entry points may be called +directly, but using the BASIC ROM is not possible without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $400 (as in the standard setup). + + <tag/Stack/ + The C runtime stack is located at $BFFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing C128 specific code may use the <tt/c128.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/c128.h/ and declares several functions +common to all CBM platforms. + + +<sect1>C128 specific functions<p> + +The functions listed below are special for the C128. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>videomode +<item>c64mode +<item>fast +<item>slow +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/c128.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC II (the graphics + controller). See the <tt/_vic2.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/SID/</tag> + The <tt/SID/ structure allows access to the SID (the sound interface + device). See the <tt/_sid.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/VDC/</tag> + The <tt/VDC/ structure allows access to the VDC (the video display + controller). See the <tt/_vdc.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/CIA1, CIA2/</tag> + Access to the two CIA (complex interface adapter) chips is available via + the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables + is explained in <tt/_6526.h/. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the C128 at $D800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +Note: The graphics drivers for the VDC are incompatible with the extended +memory drivers using the VDC memory! + +<descrip> + <tag><tt/c128-vdc.tgi (c128_640_200_2)/</tag> + This driver was written by Maciej Witkowiak. It uses the 80 column display + and features a resolution of 640*200 with two colors and an adjustable + palette (that means that the two colors can be chosen out of the 16 VDC + colors). + + <tag><tt/c128-vdc2.tgi (c128_640_480_2)/</tag> + This driver was written by Maciej Witkowiak. This driver uses the 80 column + display and features a resolution of 640*480 with two colors and an + adjustable palette (that means that the two colors can be chosen out of the + 16 VDC colors). The driver requires 64KB VDC RAM. +</descrip><p> + +Note: The colors are translated from definitions in headers to correct VDC values +so please use definitions or VIC color numbers only. Colors <tt/GRAY3/ and <tt/BROWN/ are +missing on VDC and are translated to the two colors missing from VIC palette. + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/c128-georam.emd (c128_georam)/</tag> + A driver for the GeoRam cartridge. The driver will always assume 2048 pages + of 256 bytes each. There are no checks, so if your program knows better, + just go ahead. + + <tag><tt/c128-ram.emd (c128_ram)/</tag> + An extended memory driver for the RAM in page 1. The common memory area is + excluded, so this driver supports 251 pages of 256 bytes each. + + <tag><tt/c128-ram2.emd (c128_ram2)/</tag> + + An extended memory driver for the RAM in pages 1-3. The common memory area + is excluded, so this driver supports up to 731 pages of 256 bytes each. The + driver can be used as a full replacement for <tt/c128-ram.emd/, because RAM + in pages 2+3 is autodetected, but it's larger and there are not many + machines with RAM in banks 2+3, so it has been made a separate driver. The + additional code was contributed by Marco van den Heuvel. + + <tag><tt/c128-ramcart.emd (c128_ramcart)/</tag> + A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. + Will test the hardware for the available RAM. + + <tag><tt/c128-reu.emd (c128_reu)/</tag> + A driver for the CBM REUs. The driver will determine from the connected REU + if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, + but since there are no range checks, the application can use more memory if + it has better knowledge about the hardware than the driver. + + <tag><tt/c128-vdc.emd (c128_vdc)/</tag> + A driver for the VDC memory of the C128 written and contributed by Maciej + Witkowiak. Autodetects the amount of memory available (16 or 64K) and offers + 64 or 256 pages of 256 bytes each. Note: This driver is incompatible with + any of the graphics drivers using the VDC! + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/c128-ptvjoy.joy (c128_ptvjoy)/</tag> + Driver for the Protovision 4-player adapter originally written by Groepaz + for the C64 and converted for the C128 by me. See <htmlurl + url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and + building instructions. Up to four joysticks are supported. + + <tag><tt/c128-stdjoy.joy (c128_stdjoy)/</tag> + Supports up to two joysticks connected to the standard joysticks port of + the C128. + +</descrip><p> + + + +<sect1>Mouse drivers<p> + +<descrip> + + <tag><tt/c128-1351.mou (c128_1351)/</tag> + Supports a standard mouse connected to port #0 of the C128. + + <tag><tt/c128-joy.mou (c128_joymouse)/</tag> + Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port + #1 of the C128. + + <tag><tt/c128-pot.mou (c128_potmouse)/</tag> + Supports a potentiometer device e.g. Koala Pad connected to port #1 of + the C128. + +</descrip><p> + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/c128-swlink.ser (c128_swlink)/</tag> + Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow + control (RTS/CTS) and interrupt driven receives. Note that because of the + peculiarities of the 6551 chip together with the use of the NMI, transmits + are not interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + + The driver uses the RS232 variables and buffers of the kernal (buffers at + $C00 and $D00). + +</descrip><p> + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the C128 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/c16.sgml b/doc/c16.sgml new file mode 100644 index 000000000..110082a19 --- /dev/null +++ b/doc/c16.sgml @@ -0,0 +1,274 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 16/116 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-15 + +<abstract> +An overview over the C16 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the C16 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, C16/116 specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that C16 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + +Since the C16/C116 and the Commodore Plus/4 are almost identical (the former +don't have the 6551 ACIA and only 16KB of memory), the <htmlurl +url="plus4.html" name="Plus/4 documentation"> is also worth a look. The +difference between both cc65 targets is that the Plus/4 runtime uses banking +to support full 64K RAM, while the C16 does not use banking and supports up to +32K RAM. Because banking is not needed, most C16 programs will be somewhat +smaller than the same program compiled for the Plus/4. However, programs C16 +will always run on the Plus/4, while the reverse is not necessarily true. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the C16/116 +target is a machine language program with a one line BASIC stub which, calls +the machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the kernal and basic +banked in. This gives a usable memory range of $1000 - $4000 +(or $8000 if the machine is equipped with 32K RAM or more). Having the +kernal and basic ROMs banked in means, that ROM entry points may be called +directly from user code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $C00 (as in the standard setup). + + <tag/Color RAM/ + The color RAM is located at $800 (standard location). + + <tag/Stack/ + The C runtime stack is located at $3FFF ($7FFF in case of a + machine with 32K of memory or more) and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing C16 specific code may use the <tt/c16.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/c16.h/ and declares several functions +common to all CBM platforms. + +Please note that most of the header file declarations from the <tt/c16.h/ +header file are shared between the C16 and Plus/4 configurations. For this +reason, most of it is located in a common header file named <tt/cbm264.h/. + + + +<sect1>C16/C116 specific functions<p> + +There are currently no special C16/C116 functions. + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/c16.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/TED/</tag> + The <tt/TED/ structure allows access to the TED chip. See the + <tt/_ted.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the C16 at $0800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the C16/C116. + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/c16-ram.emd (c16_ram)/</tag> + A driver for the hidden RAM below the BASIC and KERNAL ROMs. Supports 125 + pages with 256 bytes each if the machine is equipped with 64K of memory + (a Plus/4 or a memory extended C16/116). + +</descrip><p> + + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/c16-stdjoy.joy (c16_stdjoy)/</tag> + Supports up to two joysticks connected to the standard joysticks port of + the Commodore 16/116. + +</descrip><p> + + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). + + +<sect1>RS232 device drivers<p> + +The Commodore 16 does not have a builtin ACIA and no RS232 extensions are +known. For this reason, there are no RS232 drivers available. Please note that +the standard Plus/4 driver will <em>not</em> run together with the C16 +library, because the latter does not support interrupts needed by the driver. + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the C16 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + + diff --git a/doc/c64.sgml b/doc/c64.sgml new file mode 100644 index 000000000..2e6a37e77 --- /dev/null +++ b/doc/c64.sgml @@ -0,0 +1,405 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 64 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-09-23 + +<abstract> +An overview over the C64 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the C64 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, C64 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that C64 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the C64 target +is a machine language program with a one line BASIC stub, which calls the +machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and the +kernal ROM enabled (memory under the kernal may be used for graphics or as +extended memory - see the sections about graphics and extended memory +drivers). The BASIC ROM is disabled, which gives a usable memory range of +$0800 - $CFFF. This means that kernal entry points may be called +directly, but using the BASIC ROM is not possible without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $400 (as in the standard setup). + + <tag/Stack/ + The C runtime stack is located at $CFFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + +<sect>Linker configurations<p> + +The ld65 linker comes with a builtin config file for the Commodore 64, +which is used via <tt/-t c64/ (and displayed via <tt/--dump-config c64/). The +c64 package comes with additional secondary linker config files, which are +used via <tt/-C <configfile>/. + + +<sect1>builtin config file<p> + +The builtin configuration is tailored to C programs. It supplies the load +address and a small BASIC stub that starts the compiled program using a SYS +command. + + +<sect1><tt/c64-asm.cfg/<p> + +This configuration is made for assembler programmers who don't need a special +setup. The default start address is $801. It can be changed with the +linker command line option <tt/--start-addr/. All standard segments with the +exception of <tt/zeropage/ are written to the output file and a two byte load +address is prepended. + +To use this config file, assemble with <tt/-t c64/ and link with <tt/-C +c64-asm.cfg/. The former will make sure that correct character translation is +in effect, while the latter supplies the actual config. When using <tt/cl65/, +use both command line options. + +Sample command line for <tt/cl65/: + +<tscreen><verb> +cl65 -o file.prg -t c64 -C c64-asm.cfg source.s +</verb></tscreen> + +To generate code that loads to $C000: + +<tscreen><verb> +cl65 -o file.prg --start-addr $C000 -t c64 -C c64-asm.cfg source.s +</verb></tscreen> + +It is also possible to add a small BASIC header to the program, that uses SYS +to jump to the program entry point (which is the start of the code segment). +The advantage is that the program can be started using RUN. + +To generate a program with a BASIC SYS header, use + +<tscreen><verb> +cl65 -o file.prg -u __EXEHDR__ -t c64 -C c64-asm.cfg source.s +</verb></tscreen> + +Please note that in this case a changed start address doesn't make sense, +since the program must be loaded to the BASIC start address. + + +<sect>Platform specific header files<p> + +Programs containing C64 specific code may use the <tt/c64.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/c64.h/ and declares several functions +common to all CBM platforms. + + +<sect1>C64 specific functions<p> + +The functions listed below are special for the C64. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>get_ostype +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/c64.h/ header file do allow +access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC II (the graphics + controller). See the <tt/_vic2.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/SID/</tag> + The <tt/SID/ structure allows access to the SID (the sound interface + device). See the <tt/_sid.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/CIA1, CIA2/</tag> + Access to the two CIA (complex interface adapter) chips is available via + the <tt/CIA1/ and <tt/CIA2/ variables. The structure behind these variables + is explained in <tt/_6526.h/. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the C64 at $D800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<em>Note:</em> All available graphics drivers for the TGI interface will use +the space below the I/O area and kernal ROM, so you can have hires graphics in +the standard setup without any memory loss or need for a changed +configuration. + +<descrip> + <tag><tt/c64-hi.tgi (c64_320_200_2)/</tag> + This driver features a resolution of 320*200 with two colors and an + adjustable palette (that means that the two colors can be chosen out of a + palette of the 16 C64 colors). +</descrip><p> + + +<sect1>Extended memory drivers<p> + +<descrip> + + <tag><tt/c64-c256k.emd (c64_c256k)/</tag> + A driver for the C64 256K memory expansion. This driver offers 768 pages of + 256 bytes each. Written and contributed by Marco van den Heuvel. + + <tag><tt/c64-dqbb.emd (c64_dqbb)/</tag> + A driver for the Double Quick Brown Box cartridge. This driver offers + 64 pages of 256 bytes each. Written and contributed by Marco van den Heuvel. + + <tag><tt/c64-georam.emd (c64_georam)/</tag> + A driver for the Berkeley Softworks GeoRam cartridge. The driver will + determine the available RAM from the connected cartridge. It supports 64KB + up to 2048KB of RAM. + + <tag><tt/c64-isepic.emd (c64_isepic)/</tag> + A driver for the ISEPIC cartridge. This driver offers just 8 pages of 256 + bytes each. Written and contributed by Marco van den Heuvel. + + <tag><tt/c64-ram.emd (c64_ram)/</tag> + A driver for the hidden RAM below the I/O area and kernal ROM. Supports 48 + 256 byte pages. Please note that this driver is incompatible with any of the + graphics drivers! + + <tag><tt/c64-ramcart.emd (c64_ramcart)/</tag> + A driver for the RamCart 64/128 written and contributed by Maciej Witkowiak. + Will test the hardware for the available RAM. + + <tag><tt/c64-reu.emd (c64_reu)/</tag> + A driver for the CBM REUs. The driver will determine from the connected REU + if it supports 128KB of RAM or more. In the latter case, 256KB are assumed, + but since there are no range checks, the application can use more memory if + it has better knowledge about the hardware than the driver. + + <tag><tt/c64-vdc.emd (c64_vdc)/</tag> + A driver for the VDC memory of the C128. Written and contributed by Maciej + Witkowiak. Can be used if the program is running in C64 mode of the C128. + Autodetects the amount of memory available (16 or 64K) and offers 64 or 256 + pages of 256 bytes each. + + <tag><tt/dtv-himem.emd (dtv_himem)/</tag> + A driver for the C64 D2TV (the second or PAL version). This driver offers + indeed 7680 pages of 256 bytes each. + +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/c64-hitjoy.joy (c64_hitjoy)/</tag> + Driver for the Digital Excess & Hitmen adapter contributed by Groepaz. See + <htmlurl url="http://www.digitalexcess.de/downloads/productions.php" + name="http://www.digitalexcess.de/downloads/productions.php"> on + instructions how to build one. Up to four joysticks are supported. + + <tag><tt/c64-ptvjoy.joy (c64_ptvjoy)/</tag> + Driver for the Protovision 4-player adapter contributed by Groepaz. See + <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and + building instructions. Up to four joysticks are supported. + + <tag><tt/c64-stdjoy.joy (c64_stdjoy)/</tag> + Supports up to two standard joysticks connected to the joysticks port of + the C64. + + <tag><tt/c64-numpad.joy (c64_numpad)/</tag> + Supports one joystick emulated by the numberpad of the C128 in C64 mode, + the firebutton is labeled &dquot;5&dquot; and ENTER. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +<descrip> + + <tag><tt/c64-1351.mou (c64_1351)/</tag> + Supports a standard mouse connected to port #0 of the C64. + + <tag><tt/c64-joy.mou (c64_joymouse)/</tag> + Supports a mouse emulated by a standard joystick e.g. 1350 mouse in port + #1 of the C64. + + <tag><tt/c64-pot.mou (c64_potmouse)/</tag> + Supports a potentiometer device e.g. Koala Pad connected to port #1 of + the C64. + +</descrip><p> + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/c64-swlink.ser (c64_swlink)/</tag> + Driver for the SwiftLink cartridge. Supports up to 38400 baud, hardware flow + control (RTS/CTS) and interrupt driven receives. Note that because of the + peculiarities of the 6551 chip together with the use of the NMI, transmits + are not interrupt driven, and the transceiver blocks if the receiver asserts + flow control because of a full buffer. + +</descrip><p> + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Escape code<p> + +For an Esc press CTRL and [ key. + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the C64 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/ca65.sgml b/doc/ca65.sgml new file mode 100644 index 000000000..00d72db56 --- /dev/null +++ b/doc/ca65.sgml @@ -0,0 +1,4786 @@ +<!doctype linuxdoc system> <!-- -*- text-mode -*- --> + +<article> +<title>ca65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2000-07-19, 2000-11-29, 2001-10-02, 2005-09-08 + +<abstract> +ca65 is a powerful macro assembler for the 6502, 65C02 and 65816 CPUs. It is +used as a companion assembler for the cc65 crosscompiler, but it may also be +used as a standalone product. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +ca65 is a replacement for the ra65 assembler that was part of the cc65 C +compiler, originally developed by John R. Dunning. I had some problems with +ra65 and the copyright does not permit some things which I wanted to be +possible, so I decided to write a completely new assembler/linker/archiver +suite for the cc65 compiler. ca65 is part of this suite. + +Some parts of the assembler (code generation and some routines for symbol +table handling) are taken from an older crossassembler named a816 written +by me a long time ago. + + +<sect1>Design criteria<p> + +Here's a list of the design criteria, that I considered important for the +development: + +<itemize> + +<item> The assembler must support macros. Macros are not essential, but they + make some things easier, especially when you use the assembler in the + backend of a compiler. +<item> The assembler must support the newer 65C02 and 65816 CPUs. I have been + thinking about a 65816 backend for the C compiler, and even my old + a816 assembler had support for these CPUs, so this wasn't really a + problem. +<item> The assembler must produce relocatable code. This is necessary for the + compiler support, and it is more convenient. +<item> Conditional assembly must be supported. This is a must for bigger + projects written in assembler (like Elite128). +<item> The assembler must support segments, and it must support more than + three segments (this is the count, most other assemblers support). + Having more than one code segments helps developing code for systems + with a divided ROM area (like the C64). +<item> The linker must be able to resolve arbitrary expressions. It should + be able to get things like +<tscreen><verb> + .import S1, S2 + .export Special + Special = 2*S1 + S2/7 +</verb></tscreen> + right. +<item> True lexical nesting for symbols. This is very convenient for larger + assembly projects. +<item> "Cheap" local symbols without lexical nesting for those quick, late + night hacks. +<item> I liked the idea of "options" as Anre Fachats .o65 format has it, so I + introduced the concept into the object file format use by the new cc65 + binutils. +<item> The assembler will be a one pass assembler. There was no real need for + this decision, but I've written several multipass assemblers, and it + started to get boring. A one pass assembler needs much more elaborated + data structures, and because of that it's much more fun:-) +<item> Non-GPLed code that may be used in any project without restrictions or + fear of "GPL infecting" other code. +</itemize> +<p> + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The assembler accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: ca65 [options] file +Short options: + -D name[=value] Define a symbol + -I dir Set an include directory search path + -U Mark unresolved symbols as import + -V Print the assembler version + -W n Set warning level n + -d Debug mode + -g Add debug info to object file + -h Help (this text) + -i Ignore case of symbols + -l name Create a listing file if assembly was ok + -mm model Set the memory model + -o name Name the output file + -s Enable smart mode + -t sys Set the target system + -v Increase verbosity + +Long options: + --auto-import Mark unresolved symbols as import + --bin-include-dir dir Set a search path for binary includes + --cpu type Set cpu type + --create-dep name Create a make dependency file + --create-full-dep name Create a full make dependency file + --debug Debug mode + --debug-info Add debug info to object file + --feature name Set an emulation feature + --forget-inc-paths Forget include search paths + --help Help (this text) + --ignore-case Ignore case of symbols + --include-dir dir Set an include directory search path + --large-alignment Don't warn about large alignments + --listing name Create a listing file if assembly was ok + --list-bytes n Maximum number of bytes per listing line + --macpack-dir dir Set a macro package directory + --memory-model model Set the memory model + --pagelength n Set the page length for the listing + --relax-checks Relax some checks (see docs) + --smart Enable smart mode + --target sys Set the target system + --verbose Increase verbosity + --version Print the assembler version +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <label id="option--bin-include-dir"> + <tag><tt>--bin-include-dir dir</tt></tag> + + Name a directory which is searched for binary include files. The option + may be used more than once to specify more than one directory to search. The + current directory is always searched first before considering any + additional directories. See also the section about <ref id="search-paths" + name="search paths">. + + + <label id="option--cpu"> + <tag><tt>--cpu type</tt></tag> + + Set the default for the CPU type. The option takes a parameter, which + may be one of + + 6502, 65SC02, 65C02, 65816, sunplus, sweet16, HuC6280 + + The sunplus cpu is not available in the freeware version, because the + instruction set is "proprietary and confidential". + + + <label id="option-create-dep"> + <tag><tt>--create-dep name</tt></tag> + + Tells the assembler to generate a file containing the dependency list for + the assembled module in makefile syntax. The output is written to a file + with the given name. The output does not include files passed via debug + information to the assembler. + + + <label id="option-create-full-dep"> + <tag><tt>--create-full-dep name</tt></tag> + + Tells the assembler to generate a file containing the dependency list for + the assembled module in makefile syntax. The output is written to a file + with the given name. The output does include files passed via debug + information to the assembler. + + + <tag><tt>-d, --debug</tt></tag> + + Enables debug mode, something that should not be needed for mere + mortals:-) + + + <label id="option--feature"> + <tag><tt>--feature name</tt></tag> + + Enable an emulation feature. This is identical as using <tt/.FEATURE/ + in the source with two exceptions: Feature names must be lower case, and + each feature must be specified by using an extra <tt/--feature/ option, + comma separated lists are not allowed. + + See the discussion of the <tt><ref id=".FEATURE" name=".FEATURE"></tt> + command for a list of emulation features. + + + <label id="option--forget-inc-paths"> + <tag><tt>--forget-inc-paths</tt></tag> + + Forget the builtin include paths. This is most useful when building + customized assembler modules, in which case the standard header files should + be ignored. + + + <label id="option-g"> + <tag><tt>-g, --debug-info</tt></tag> + + When this option (or the equivalent control command <tt/.DEBUGINFO/) is + used, the assembler will add a section to the object file that contains + all symbols (including local ones) together with the symbol values and + source file positions. The linker will put these additional symbols into + the VICE label file, so even local symbols can be seen in the VICE + monitor. + + + <label id="option-h"> + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option-i"> + <tag><tt>-i, --ignore-case</tt></tag> + + This option makes the assembler case insensitive on identifiers and labels. + This option will override the default, but may itself be overridden by the + <tt><ref id=".CASE" name=".CASE"></tt> control command. + + + <label id="option-l"> + <tag><tt>-l name, --listing name</tt></tag> + + Generate an assembler listing with the given name. A listing file will + never be generated in case of assembly errors. + + + <label id="option--large-alignment"> + <tag><tt>--large-alignment</tt></tag> + + Disable warnings about a large combined alignment. See the discussion of the + <tt><ref id=".ALIGN" name=".ALIGN"></tt> directive for futher information. + + + <label id="option--list-bytes"> + <tag><tt>--list-bytes n</tt></tag> + + Set the maximum number of bytes printed in the listing for one line of + input. See the <tt><ref id=".LISTBYTES" name=".LISTBYTES"></tt> directive + for more information. The value zero can be used to encode an unlimited + number of printed bytes. + + + <label id="option--macpack-dir"> + <tag><tt>--macpack-dir dir</tt></tag> + + This options allows to specify a directory containing macro files that are + used instead of the builtin images when a <tt><ref id=".MACPACK" + name=".MACPACK"></tt> directive is encountered. If <tt>--macpack-dir</tt> + was specified, a <tt>.mac</tt> extension is added to the package name and + the resulting file is loaded from the given directory. This is most useful + when debugging the builtin macro packages. + + + <label id="option-mm"> + <tag><tt>-mm model, --memory-model model</tt></tag> + + Define the default memory model. Possible model specifiers are near, far and + huge. + + + <label id="option-o"> + <tag><tt>-o name</tt></tag> + + The default output name is the name of the input file with the extension + replaced by ".o". If you don't like that, you may give another name with + the -o option. The output file will be placed in the same directory as + the source file, or, if -o is given, the full path in this name is used. + + + <label id="option--pagelength"> + <tag><tt>--pagelength n</tt></tag> + + sets the length of a listing page in lines. See the <tt><ref + id=".PAGELENGTH" name=".PAGELENGTH"></tt> directive for more information. + + + <label id="option--relax-checks"> + <tag><tt>--relax-checks</tt></tag> + + Relax some checks done by the assembler. This will allow code that is an + error in most cases and flagged as such by the assembler, but can be valid + in special situations. + + Examples are: +<itemize> +<item>Short branches between two different segments. +<item>Byte sized address loads where the address is not a zeropage address. +</itemize> + + + <label id="option-s"> + <tag><tt>-s, --smart-mode</tt></tag> + + In smart mode (enabled by -s or the <tt><ref id=".SMART" name=".SMART"></tt> + pseudo instruction) the assembler will track usage of the <tt/REP/ and + <tt/SEP/ instructions in 65816 mode and update the operand sizes + accordingly. If the operand of such an instruction cannot be evaluated by + the assembler (for example, because the operand is an imported symbol), a + warning is issued. + + Beware: Since the assembler cannot trace the execution flow this may + lead to false results in some cases. If in doubt, use the .ixx and .axx + instructions to tell the assembler about the current settings. Smart + mode is off by default. + + + <label id="option-t"> + <tag><tt>-t sys, --target sys</tt></tag> + + Set the target system. This will enable translation of character strings and + character constants into the character set of the target platform. The + default for the target system is "none", which means that no translation + will take place. The assembler supports the same target systems as the + compiler, see there for a list. + + Depending on the target, the default CPU type is also set. This can be + overriden by using the <tt/<ref id="option--cpu" name="--cpu">/ option. + + + <label id="option-v"> + <tag><tt>-v, --verbose</tt></tag> + + Increase the assembler verbosity. Usually only needed for debugging + purposes. You may use this option more than one time for even more + verbose output. + + + <label id="option-D"> + <tag><tt>-D</tt></tag> + + This option allows you to define symbols on the command line. Without a + value, the symbol is defined with the value zero. When giving a value, + you may use the '$' prefix for hexadecimal symbols. Please note + that for some operating systems, '$' has a special meaning, so + you may have to quote the expression. + + + <label id="option-I"> + <tag><tt>-I dir, --include-dir dir</tt></tag> + + Name a directory which is searched for include files. The option may be + used more than once to specify more than one directory to search. The + current directory is always searched first before considering any + additional directories. See also the section about <ref id="search-paths" + name="search paths">. + + + <label id="option-U"> + <tag><tt>-U, --auto-import</tt></tag> + + Mark symbols that are not defined in the sources as imported symbols. This + should be used with care since it delays error messages about typos and such + until the linker is run. The compiler uses the equivalent of this switch + (<tt><ref id=".AUTOIMPORT" name=".AUTOIMPORT"></tt>) to enable auto imported + symbols for the runtime library. However, the compiler is supposed to + generate code that runs through the assembler without problems, something + which is not always true for assembler programmers. + + + <label id="option-V"> + <tag><tt>-V, --version</tt></tag> + + Print the version number of the assembler. If you send any suggestions + or bugfixes, please include the version number. + + + <label id="option-W"> + <tag><tt>-Wn</tt></tag> + + Set the warning level for the assembler. Using -W2 the assembler will + even warn about such things like unused imported symbols. The default + warning level is 1, and it would probably be silly to set it to + something lower. + +</descrip> +<p> + + + +<sect>Search paths<label id="search-paths"><p> + +Normal include files are searched in the following places: + +<enum> +<item>The current directory. +<item>A compiled-in directory, which is often <tt>/usr/lib/cc65/asminc</tt> + on Linux systems. +<item>The value of the environment variable <tt/CA65_INC/ if it is defined. +<item>A subdirectory named <tt/asminc/ of the directory defined in the + environment variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt/<ref id="option-I" name="-I">/ option +on the command line. +</enum> + +Binary include files are searched in the following places: + +<enum> +<item>The current directory. +<item>Any directory added with the <tt/<ref id="option--bin-include-dir" +name="--bin-include-dir">/ option on the command line. +</enum> + + + +<sect>Input format<p> + +<sect1>Assembler syntax<p> + +The assembler accepts the standard 6502/65816 assembler syntax. One line may +contain a label (which is identified by a colon), and, in addition to the +label, an assembler mnemonic, a macro, or a control command (see section <ref +id="control-commands" name="Control Commands"> for supported control +commands). Alternatively, the line may contain a symbol definition using +the '=' token. Everything after a semicolon is handled as a comment (that is, +it is ignored). + +Here are some examples for valid input lines: + +<tscreen><verb> + Label: ; A label and a comment + lda #$20 ; A 6502 instruction plus comment + L1: ldx #$20 ; Same with label + L2: .byte "Hello world" ; Label plus control command + mymac $20 ; Macro expansion + MySym = 3*L1 ; Symbol definition + MaSym = Label ; Another symbol +</verb></tscreen> + +The assembler accepts + +<itemize> +<item>all valid 6502 mnemonics when in 6502 mode (the default or after the + <tt><ref id=".P02" name=".P02"></tt> command was given). +<item>all valid 6502 mnemonics plus a set of illegal instructions when in + <ref id="6502X-mode" name="6502X mode">. +<item>all valid 65SC02 mnemonics when in 65SC02 mode (after the + <tt><ref id=".PSC02" name=".PSC02"></tt> command was given). +<item>all valid 65C02 mnemonics when in 65C02 mode (after the + <tt><ref id=".PC02" name=".PC02"></tt> command was given). +<item>all valid 65618 mnemonics when in 65816 mode (after the + <tt><ref id=".P816" name=".P816"></tt> command was given). +<item>all valid SunPlus mnemonics when in SunPlus mode (after the + <tt><ref id=".SUNPLUS" name=".SUNPLUS"></tt> command was given). +</itemize> + + +<sect1>65816 mode<p> + +In 65816 mode several aliases are accepted in addition to the official +mnemonics: + +<tscreen><verb> + BGE is an alias for BCS + BLT is an alias for BCC + CPA is an alias for CMP + DEA is an alias for DEC A + INA is an alias for INC A + SWA is an alias for XBA + TAD is an alias for TCD + TAS is an alias for TCS + TDA is an alias for TDC + TSA is an alias for TSC +</verb></tscreen> + + + +<sect1>6502X mode<label id="6502X-mode"><p> + +6502X mode is an extension to the normal 6502 mode. In this mode, several +mnemonics for illegal instructions of the NMOS 6502 CPUs are accepted. Since +these instructions are illegal, there are no official mnemonics for them. The +unofficial ones are taken from <htmlurl +url="http://www.oxyron.de/html/opcodes02.html" +name="http://www.oxyron.de/html/opcodes02.html">. Please note that only the +ones marked as "stable" are supported. The following table uses information +from the mentioned web page, for more information, see there. + +<itemize> +<item><tt>ALR: A:=(A and #{imm})/2;</tt> +<item><tt>ANC: A:=A and #{imm};</tt> Generates opcode $0B. +<item><tt>ARR: A:=(A and #{imm})/2;</tt> +<item><tt>AXS: X:=A and X-#{imm};</tt> +<item><tt>DCP: {adr}:={adr}-1; A-{adr};</tt> +<item><tt>ISC: {adr}:={adr}+1; A:=A-{adr};</tt> +<item><tt>LAS: A,X,S:={adr} and S;</tt> +<item><tt>LAX: A,X:={adr};</tt> +<item><tt>RLA: {adr}:={adr}rol; A:=A and {adr};</tt> +<item><tt>RRA: {adr}:={adr}ror; A:=A adc {adr};</tt> +<item><tt>SAX: {adr}:=A and X;</tt> +<item><tt>SLO: {adr}:={adr}*2; A:=A or {adr};</tt> +<item><tt>SRE: {adr}:={adr}/2; A:=A xor {adr};</tt> +</itemize> + + + +<sect1>sweet16 mode<label id="sweet16-mode"><p> + +SWEET 16 is an interpreter for a pseudo 16 bit CPU written by Steve Wozniak +for the Apple ][ machines. It is available in the Apple ][ ROM. ca65 can +generate code for this pseudo CPU when switched into sweet16 mode. The +following is special in sweet16 mode: + +<itemize> + +<item>The '@' character denotes indirect addressing and is no longer available +for cheap local labels. If you need cheap local labels, you will have to +switch to another lead character using the <tt/<ref id=".LOCALCHAR" +name=".LOCALCHAR">/ command. + +<item>Registers are specified using <tt/R0/ .. <tt/R15/. In sweet16 mode, +these identifiers are reserved words. + +</itemize> + +Please note that the assembler does neither supply the interpreter needed for +SWEET 16 code, nor the zero page locations needed for the SWEET 16 registers, +nor does it call the interpreter. All this must be done by your program. Apple +][ programmers do probably know how to use sweet16 mode. + +For more information about SWEET 16, see +<htmlurl url="http://www.6502.org/source/interpreters/sweet16.htm" +name="http://www.6502.org/source/interpreters/sweet16.htm">. + + +<sect1>Number format<p> + +For literal values, the assembler accepts the widely used number formats: A +preceding '$' or a trailing 'h' denotes a hex value, a preceding '%' +denotes a binary value, and a bare number is interpreted as a decimal. There +are currently no octal values and no floats. + + +<sect1>Conditional assembly<p> + +Please note that when using the conditional directives (<tt/.IF/ and friends), +the input must consist of valid assembler tokens, even in <tt/.IF/ branches +that are not assembled. The reason for this behaviour is that the assembler +must still be able to detect the ending tokens (like <tt/.ENDIF/), so +conversion of the input stream into tokens still takes place. As a consequence +conditional assembly directives may <bf/not/ be used to prevent normal text +(used as a comment or similar) from being assembled. <p> + + +<sect>Expressions<p> + + +<sect1>Expression evaluation<p> + +All expressions are evaluated with (at least) 32 bit precision. An +expression may contain constant values and any combination of internal and +external symbols. Expressions that cannot be evaluated at assembly time +are stored inside the object file for evaluation by the linker. +Expressions referencing imported symbols must always be evaluated by the +linker. + + +<sect1>Size of an expression result<p> + +Sometimes, the assembler must know about the size of the value that is the +result of an expression. This is usually the case, if a decision has to be +made, to generate a zero page or an absolute memory references. In this +case, the assembler has to make some assumptions about the result of an +expression: + +<itemize> +<item> If the result of an expression is constant, the actual value is + checked to see if it's a byte sized expression or not. +<item> If the expression is explicitly casted to a byte sized expression by + one of the '>', '<' or '^' operators, it is a byte expression. +<item> If this is not the case, and the expression contains a symbol, + explicitly declared as zero page symbol (by one of the .importzp or + .exportzp instructions), then the whole expression is assumed to be + byte sized. +<item> If the expression contains symbols that are not defined, and these + symbols are local symbols, the enclosing scopes are searched for a + symbol with the same name. If one exists and this symbol is defined, + its attributes are used to determine the result size. +<item> In all other cases the expression is assumed to be word sized. +</itemize> + +Note: If the assembler is not able to evaluate the expression at assembly +time, the linker will evaluate it and check for range errors as soon as +the result is known. + + +<sect1>Boolean expressions<p> + +In the context of a boolean expression, any non zero value is evaluated as +true, any other value to false. The result of a boolean expression is 1 if +it's true, and zero if it's false. There are boolean operators with extreme +low precedence with version 2.x (where x > 0). The <tt/.AND/ and <tt/.OR/ +operators are shortcut operators. That is, if the result of the expression is +already known, after evaluating the left hand side, the right hand side is +not evaluated. + + +<sect1>Constant expressions<p> + +Sometimes an expression must evaluate to a constant without looking at any +further input. One such example is the <tt/<ref id=".IF" name=".IF">/ command +that decides if parts of the code are assembled or not. An expression used in +the <tt/.IF/ command cannot reference a symbol defined later, because the +decision about the <tt/.IF/ must be made at the point when it is read. If the +expression used in such a context contains only constant numerical values, +there is no problem. When unresolvable symbols are involved it may get harder +for the assembler to determine if the expression is actually constant, and it +is even possible to create expressions that aren't recognized as constant. +Simplifying the expressions will often help. + +In cases where the result of the expression is not needed immediately, the +assembler will delay evaluation until all input is read, at which point all +symbols are known. So using arbitrary complex constant expressions is no +problem in most cases. + + + +<sect1>Available operators<label id="operators"><p> + +<table> +<tabular ca="clc"> +<bf/Operator/| <bf/Description/| <bf/Precedence/@<hline> +| Built-in string functions| 0@ +||~@ +| Built-in pseudo-variables| 1@ +| Built-in pseudo-functions| 1@ ++| Unary positive| 1@ +-| Unary negative| 1@ +˜<newline> +.BITNOT| Unary bitwise not| 1@ +<<newline> +.LOBYTE| Unary low-byte operator| 1@ +><newline> +.HIBYTE| Unary high-byte operator| 1@ +^<newline> +.BANKBYTE| Unary bank-byte operator| 1@ +||~@ +*| Multiplication| 2@ +/| Division| 2@ +.MOD| Modulo operator| 2@ +&<newline> +.BITAND| Bitwise and| 2@ +^<newline> +.BITXOR| Binary bitwise xor| 2@ +<<<newline> +.SHL| Shift-left operator| 2@ +>><newline> +.SHR| Shift-right operator| 2@ +||~@ ++| Binary addition| 3@ +-| Binary subtraction| 3@ +|<newline> +.BITOR| Bitwise or| 3@ +||~@ += | Compare operator (equal)| 4@ +<>| Compare operator (not equal)| 4@ +<| Compare operator (less)| 4@ +>| Compare operator (greater)| 4@ +<=| Compare operator (less or equal)| 4@ +>=| Compare operator (greater or equal)| 4@ +||~@ +&&<newline> +.AND| Boolean and| 5@ +.XOR| Boolean xor| 5@ +||~@ +||<newline> +.OR| Boolean or| 6@ +||~@ +!<newline> +.NOT| Boolean not| 7@<hline> +</tabular> +<caption>Available operators, sorted by precedence +</table> + +To force a specific order of evaluation, parentheses may be used, as usual. + + + +<sect>Symbols and labels<p> + +A symbol or label is an identifier that starts with a letter and is followed +by letters and digits. Depending on some features enabled (see +<tt><ref id="at_in_identifiers" name="at_in_identifiers"></tt>, +<tt><ref id="dollar_in_identifiers" name="dollar_in_identifiers"></tt> and +<tt><ref id="leading_dot_in_identifiers" name="leading_dot_in_identifiers"></tt>) +other characters may be present. Use of identifiers consisting of a single +character will not work in all cases, because some of these identifiers are +reserved keywords (for example "A" is not a valid identifier for a label, +because it is the keyword for the accumulator). + +The assembler allows you to use symbols instead of naked values to make +the source more readable. There are a lot of different ways to define and +use symbols and labels, giving a lot of flexibility. + +<sect1>Numeric constants<p> + +Numeric constants are defined using the equal sign or the label assignment +operator. After doing + +<tscreen><verb> + two = 2 +</verb></tscreen> + +may use the symbol "two" in every place where a number is expected, and it is +evaluated to the value 2 in this context. The label assignment operator is +almost identical, but causes the symbol to be marked as a label, so it may be +handled differently in a debugger: + +<tscreen><verb> + io := $d000 +</verb></tscreen> + +The right side can of course be an expression: + +<tscreen><verb> + four = two * two +</verb></tscreen> + + +<label id="variables"> +<sect1>Numeric variables<p> + +Within macros and other control structures (<tt><ref id=".REPEAT" +name=".REPEAT"></tt>, ...) it is sometimes useful to have some sort of +variable. This can be achieved by the <tt>.SET</tt> operator. It creates a +symbol that may get assigned a different value later: + +<tscreen><verb> + four .set 4 + lda #four ; Loads 4 into A + four .set 3 + lda #four ; Loads 3 into A +</verb></tscreen> + +Since the value of the symbol can change later, it must be possible to +evaluate it when used (no delayed evaluation as with normal symbols). So the +expression used as the value must be constant. + +Following is an example for a macro that generates a different label each time +it is used. It uses the <tt><ref id=".SPRINTF" name=".SPRINTF"></tt> function +and a numeric variable named <tt>lcount</tt>. + +<tscreen><verb> + .lcount .set 0 ; Initialize the counter + + .macro genlab + .ident (.sprintf ("L%04X", lcount)): + lcount .set lcount + 1 + .endmacro +</verb></tscreen> + + +<sect1>Standard labels<p> + +A label is defined by writing the name of the label at the start of the line +(before any instruction mnemonic, macro or pseudo directive), followed by a +colon. This will declare a symbol with the given name and the value of the +current program counter. + + +<sect1>Local labels and symbols<p> + +Using the <tt><ref id=".PROC" name=".PROC"></tt> directive, it is possible to +create regions of code where the names of labels and symbols are local to this +region. They are not known outside of this region and cannot be accessed from +there. Such regions may be nested like PROCEDUREs in Pascal. + +See the description of the <tt><ref id=".PROC" name=".PROC"></tt> +directive for more information. + + +<sect1>Cheap local labels<p> + +Cheap local labels are defined like standard labels, but the name of the +label must begin with a special symbol (usually '@', but this can be +changed by the <tt><ref id=".LOCALCHAR" name=".LOCALCHAR"></tt> +directive). + +Cheap local labels are visible only between two non cheap labels. As soon as a +standard symbol is encountered (this may also be a local symbol if inside a +region defined with the <tt><ref id=".PROC" name=".PROC"></tt> directive), the +cheap local symbol goes out of scope. + +You may use cheap local labels as an easy way to reuse common label +names like "Loop". Here is an example: + +<tscreen><verb> + Clear: lda #$00 ; Global label + ldy #$20 + @Loop: sta Mem,y ; Local label + dey + bne @Loop ; Ok + rts + Sub: ... ; New global label + bne @Loop ; ERROR: Unknown identifier! +</verb></tscreen> + +<sect1>Unnamed labels<p> + +If you really want to write messy code, there are also unnamed labels. These +labels do not have a name (you guessed that already, didn't you?). A colon is +used to mark the absence of the name. + +Unnamed labels may be accessed by using the colon plus several minus or plus +characters as a label designator. Using the '-' characters will create a back +reference (use the n'th label backwards), using '+' will create a forward +reference (use the n'th label in forward direction). An example will help to +understand this: + +<tscreen><verb> + : lda (ptr1),y ; #1 + cmp (ptr2),y + bne :+ ; -> #2 + tax + beq :+++ ; -> #4 + iny + bne :- ; -> #1 + inc ptr1+1 + inc ptr2+1 + bne :- ; -> #1 + + : bcs :+ ; #2 -> #3 + ldx #$FF + rts + + : ldx #$01 ; #3 + : rts ; #4 +</verb></tscreen> + +As you can see from the example, unnamed labels will make even short +sections of code hard to understand, because you have to count labels +to find branch targets (this is the reason why I for my part do +prefer the "cheap" local labels). Nevertheless, unnamed labels are +convenient in some situations, so it's your decision. + +<bf/Note:/ <ref id="scopes" name="Scopes"> organize named symbols, not +unnamed ones, so scopes don't have an effect on unnamed labels. + + + +<sect1>Using macros to define labels and constants<p> + +While there are drawbacks with this approach, it may be handy in a few rare +situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is possible +to define symbols or constants that may be used elsewhere. One of the +advantages is that you can use it to define string constants (this is not +possible with the other symbol types). + +Please note: <tt/.DEFINE/ style macros do token replacements on a low level, +so the names do not adhere to scoping, diagnostics may be misleading, there +are no symbols to look up in the map file, and there is no debug info. +Especially the first problem in the list can lead to very nasty programming +errors. Because of these problems, the general advice is, <bf/NOT/ do use +<tt/.DEFINE/ if you don't have to. + +Example: + +<tscreen><verb> + .DEFINE two 2 + .DEFINE version "SOS V2.3" + + four = two * two ; Ok + .byte version ; Ok + + .PROC ; Start local scope + two = 3 ; Will give "2 = 3" - invalid! + .ENDPROC +</verb></tscreen> + + +<sect1>Symbols and <tt>.DEBUGINFO</tt><p> + +If <tt><ref id=".DEBUGINFO" name=".DEBUGINFO"></tt> is enabled (or <ref +id="option-g" name="-g"> is given on the command line), global, local and +cheap local labels are written to the object file and will be available in the +symbol file via the linker. Unnamed labels are not written to the object file, +because they don't have a name which would allow to access them. + + + +<sect>Scopes<label id="scopes"><p> + +ca65 implements several sorts of scopes for symbols. + +<sect1>Global scope<p> + +All (non cheap local) symbols that are declared outside of any nested scopes +are in global scope. + + +<sect1>Cheap locals<p> + +A special scope is the scope for cheap local symbols. It lasts from one non +local symbol to the next one, without any provisions made by the programmer. +All other scopes differ in usage but use the same concept internally. + + +<sect1>Generic nested scopes<p> + +A nested scoped for generic use is started with <tt/<ref id=".SCOPE" +name=".SCOPE">/ and closed with <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/. +The scope can have a name, in which case it is accessible from the outside by +using <ref id="scopesyntax" name="explicit scopes">. If the scope does not +have a name, all symbols created within the scope are local to the scope, and +aren't accessible from the outside. + +A nested scope can access symbols from the local or from enclosing scopes by +name without using explicit scope names. In some cases there may be +ambiguities, for example if there is a reference to a local symbol that is not +yet defined, but a symbol with the same name exists in outer scopes: + +<tscreen><verb> + .scope outer + foo = 2 + .scope inner + lda #foo + foo = 3 + .endscope + .endscope +</verb></tscreen> + +In the example above, the <tt/lda/ instruction will load the value 3 into the +accumulator, because <tt/foo/ is redefined in the scope. However: + +<tscreen><verb> + .scope outer + foo = $1234 + .scope inner + lda foo,x + foo = $12 + .endscope + .endscope +</verb></tscreen> + +Here, <tt/lda/ will still load from <tt/$12,x/, but since it is unknown to the +assembler that <tt/foo/ is a zeropage symbol when translating the instruction, +absolute mode is used instead. In fact, the assembler will not use absolute +mode by default, but it will search through the enclosing scopes for a symbol +with the given name. If one is found, the address size of this symbol is used. +This may lead to errors: + +<tscreen><verb> + .scope outer + foo = $12 + .scope inner + lda foo,x + foo = $1234 + .endscope + .endscope +</verb></tscreen> + +In this case, when the assembler sees the symbol <tt/foo/ in the <tt/lda/ +instruction, it will search for an already defined symbol <tt/foo/. It will +find <tt/foo/ in scope <tt/outer/, and a close look reveals that it is a +zeropage symbol. So the assembler will use zeropage addressing mode. If +<tt/foo/ is redefined later in scope <tt/inner/, the assembler tries to change +the address in the <tt/lda/ instruction already translated, but since the new +value needs absolute addressing mode, this fails, and an error message "Range +error" is output. + +Of course the most simple solution for the problem is to move the definition +of <tt/foo/ in scope <tt/inner/ upwards, so it precedes its use. There may be +rare cases when this cannot be done. In these cases, you can use one of the +address size override operators: + +<tscreen><verb> + .scope outer + foo = $12 + .scope inner + lda a:foo,x + foo = $1234 + .endscope + .endscope +</verb></tscreen> + +This will cause the <tt/lda/ instruction to be translated using absolute +addressing mode, which means changing the symbol reference later does not +cause any errors. + + +<sect1>Nested procedures<p> + +A nested procedure is created by use of <tt/<ref id=".PROC" name=".PROC">/. It +differs from a <tt/<ref id=".SCOPE" name=".SCOPE">/ in that it must have a +name, and a it will introduce a symbol with this name in the enclosing scope. +So + +<tscreen><verb> + .proc foo + ... + .endproc +</verb></tscreen> + +is actually the same as + +<tscreen><verb> + foo: + .scope foo + ... + .endscope +</verb></tscreen> + +This is the reason why a procedure must have a name. If you want a scope +without a name, use <tt/<ref id=".SCOPE" name=".SCOPE">/. + +<bf/Note:/ As you can see from the example above, scopes and symbols live in +different namespaces. There can be a symbol named <tt/foo/ and a scope named +<tt/foo/ without any conflicts (but see the section titled <ref +id="scopesearch" name=""Scope search order"">). + + +<sect1>Structs, unions and enums<p> + +Structs, unions and enums are explained in a <ref id="structs" name="separate +section">, I do only cover them here, because if they are declared with a +name, they open a nested scope, similar to <tt/<ref id=".SCOPE" +name=".SCOPE">/. However, when no name is specified, the behaviour is +different: In this case, no new scope will be opened, symbols declared within +a struct, union, or enum declaration will then be added to the enclosing scope +instead. + + +<sect1>Explicit scope specification<label id="scopesyntax"><p> + +Accessing symbols from other scopes is possible by using an explicit scope +specification, provided that the scope where the symbol lives in has a name. +The namespace token (<tt/::/) is used to access other scopes: + +<tscreen><verb> + .scope foo + bar: .word 0 + .endscope + + ... + lda foo::bar ; Access foo in scope bar +</verb></tscreen> + +The only way to deny access to a scope from the outside is to declare a scope +without a name (using the <tt/<ref id=".SCOPE" name=".SCOPE">/ command). + +A special syntax is used to specify the global scope: If a symbol or scope is +preceded by the namespace token, the global scope is searched: + +<tscreen><verb> + bar = 3 + + .scope foo + bar = 2 + lda #::bar ; Access the global bar (which is 3) + .endscope +</verb></tscreen> + + +<sect1>Scope search order<label id="scopesearch"><p> + +The assembler searches for a scope in a similar way as for a symbol. First, it +looks in the current scope, and then it walks up the enclosing scopes until +the scope is found. + +However, one important thing to note when using explicit scope syntax is, that +a symbol may be accessed before it is defined, but a scope may <bf/not/ be +used without a preceding definition. This means that in the following +example: + +<tscreen><verb> + .scope foo + bar = 3 + .endscope + + .scope outer + lda #foo::bar ; Will load 3, not 2! + .scope foo + bar = 2 + .endscope + .endscope +</verb></tscreen> + +the reference to the scope <tt/foo/ will use the global scope, and not the +local one, because the local one is not visible at the point where it is +referenced. + +Things get more complex if a complete chain of scopes is specified: + +<tscreen><verb> + .scope foo + .scope outer + .scope inner + bar = 1 + .endscope + .endscope + .scope another + .scope nested + lda #outer::inner::bar ; 1 + .endscope + .endscope + .endscope + + .scope outer + .scope inner + bar = 2 + .endscope + .endscope +</verb></tscreen> + +When <tt/outer::inner::bar/ is referenced in the <tt/lda/ instruction, the +assembler will first search in the local scope for a scope named <tt/outer/. +Since none is found, the enclosing scope (<tt/another/) is checked. There is +still no scope named <tt/outer/, so scope <tt/foo/ is checked, and finally +scope <tt/outer/ is found. Within this scope, <tt/inner/ is searched, and in +this scope, the assembler looks for a symbol named <tt/bar/. + +Please note that once the anchor scope is found, all following scopes +(<tt/inner/ in this case) are expected to be found exactly in this scope. The +assembler will search the scope tree only for the first scope (if it is not +anchored in the root scope). Starting from there on, there is no flexibility, +so if the scope named <tt/outer/ found by the assembler does not contain a +scope named <tt/inner/, this would be an error, even if such a pair does exist +(one level up in global scope). + +Ambiguities that may be introduced by this search algorithm may be removed by +anchoring the scope specification in the global scope. In the example above, +if you want to access the "other" symbol <tt/bar/, you would have to write: + +<tscreen><verb> + .scope foo + .scope outer + .scope inner + bar = 1 + .endscope + .endscope + .scope another + .scope nested + lda #::outer::inner::bar ; 2 + .endscope + .endscope + .endscope + + .scope outer + .scope inner + bar = 2 + .endscope + .endscope +</verb></tscreen> + + +<sect>Address sizes and memory models<label id="address-sizes"><p> + +<sect1>Address sizes<p> + +ca65 assigns each segment and each symbol an address size. This is true, even +if the symbol is not used as an address. You may also think of a value range +of the symbol instead of an address size. + +Possible address sizes are: + +<itemize> +<item>Zeropage or direct (8 bits) +<item>Absolute (16 bits) +<item>Far (24 bits) +<item>Long (32 bits) +</itemize> + +Since the assembler uses default address sizes for the segments and symbols, +it is usually not necessary to override the default behaviour. In cases, where +it is necessary, the following keywords may be used to specify address sizes: + +<itemize> +<item>DIRECT, ZEROPAGE or ZP for zeropage addressing (8 bits). +<item>ABSOLUTE, ABS or NEAR for absolute addressing (16 bits). +<item>FAR for far addressing (24 bits). +<item>LONG or DWORD for long addressing (32 bits). +</itemize> + + +<sect1>Address sizes of segments<p> + +The assembler assigns an address size to each segment. Since the +representation of a label within this segment is "segment start + offset", +labels will inherit the address size of the segment they are declared in. + +The address size of a segment may be changed, by using an optional address +size modifier. See the <tt/<ref id=".SEGMENT" name="segment directive">/ for +an explanation on how this is done. + + +<sect1>Address sizes of symbols<p> + + + + +<sect1>Memory models<p> + +The default address size of a segment depends on the memory model used. Since +labels inherit the address size from the segment they are declared in, +changing the memory model is an easy way to change the address size of many +symbols at once. + + + + +<sect>Pseudo variables<label id="pseudo-variables"><p> + +Pseudo variables are readable in all cases, and in some special cases also +writable. + +<sect1><tt>*</tt><p> + + Reading this pseudo variable will return the program counter at the start + of the current input line. + + Assignment to this variable is possible when <tt/<ref id=".FEATURE" + name=".FEATURE pc_assignment">/ is used. Note: You should not use + assignments to <tt/*/, use <tt/<ref id=".ORG" name=".ORG">/ instead. + + +<sect1><tt>.CPU</tt><label id=".CPU"><p> + + Reading this pseudo variable will give a constant integer value that + tells which CPU is currently enabled. It can also tell which instruction + set the CPU is able to translate. The value read from the pseudo variable + should be further examined by using one of the constants defined by the + "cpu" macro package (see <tt/<ref id=".MACPACK" name=".MACPACK">/). + + It may be used to replace the .IFPxx pseudo instructions or to construct + even more complex expressions. + + Example: + + <tscreen><verb> + .macpack cpu + .if (.cpu .bitand CPU_ISET_65816) + phx + phy + .else + txa + pha + tya + pha + .endif + </verb></tscreen> + + +<sect1><tt>.PARAMCOUNT</tt><label id=".PARAMCOUNT"><p> + + This builtin pseudo variable is only available in macros. It is replaced by + the actual number of parameters that were given in the macro invocation. + + Example: + + <tscreen><verb> + .macro foo arg1, arg2, arg3 + .if .paramcount <> 3 + .error "Too few parameters for macro foo" + .endif + ... + .endmacro + </verb></tscreen> + + See section <ref id="macros" name="Macros">. + + +<sect1><tt>.TIME</tt><label id=".TIME"><p> + + Reading this pseudo variable will give a constant integer value that + represents the current time in POSIX standard (as seconds since the + Epoch). + + It may be used to encode the time of translation somewhere in the created + code. + + Example: + + <tscreen><verb> + .dword .time ; Place time here + </verb></tscreen> + + +<sect1><tt>.VERSION</tt><label id=".VERSION"><p> + + Reading this pseudo variable will give the assembler version according to + the following formula: + + VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH + + It may be used to encode the assembler version or check the assembler for + special features not available with older versions. + + Example: + + Version 2.11.1 of the assembler will return $2B1 as numerical constant when + reading the pseudo variable <tt/.VERSION/. + + + +<sect>Pseudo functions<label id="pseudo-functions"><p> + +Pseudo functions expect their arguments in parenthesis, and they have a result, +either a string or an expression. + + +<sect1><tt>.BANK</tt><label id=".BANK"><p> + + The <tt/.BANK/ function is used to support systems with banked memory. The + argument is an expression with exactly one segment reference - usually a + label. The function result is the value of the <tt/bank/ attribute assigned + to the run memory area of the segment. Please see the linker documentation + for more information about memory areas and their attributes. + + The value of <tt/.BANK/ can be used to switch memory so that a memory bank + containing specific data is available. + + The <tt/bank/ attribute is a 32 bit integer and so is the result of the + <tt/.BANK/ function. You will have to use <tt><ref id=".LOBYTE" + name=".LOBYTE"></tt> or similar functions to address just part of it. + + Please note that <tt/.BANK/ will always get evaluated in the link stage, so + an expression containing <tt/.BANK/ can never be used where a constant known + result is expected (for example with <tt/.RES/). + + Example: + + <tscreen><verb> + .segment "BANK1" + .proc banked_func_1 + ... + .endproc + + .segment "BANK2" + .proc banked_func_2 + ... + .endproc + + .proc bank_table + .addr banked_func_1 + .byte <.BANK (banked_func_1) + + .addr banked_func_2 + .byte <.BANK (banked_func_2) + .endproc + </verb></tscreen> + + + +<sect1><tt>.BANKBYTE</tt><label id=".BANKBYTE"><p> + + The function returns the bank byte (that is, bits 16-23) of its argument. + It works identical to the '^' operator. + + See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>, + <tt><ref id=".LOBYTE" name=".LOBYTE"></tt> + + +<sect1><tt>.BLANK</tt><label id=".BLANK"><p> + + Builtin function. The function evaluates its argument in braces and yields + "false" if the argument is non blank (there is an argument), and "true" if + there is no argument. The token list that makes up the function argument + may optionally be enclosed in curly braces. This allows the inclusion of + tokens that would otherwise terminate the list (the closing right + parenthesis). The curly braces are not considered part of the list, a list + just consisting of curly braces is considered to be empty. + + As an example, the <tt/.IFBLANK/ statement may be replaced by + + <tscreen><verb> + .if .blank({arg}) + </verb></tscreen> + + + +<sect1><tt>.CONCAT</tt><label id=".CONCAT"><p> + + Builtin string function. The function allows to concatenate a list of string + constants separated by commas. The result is a string constant that is the + concatenation of all arguments. This function is most useful in macros and + when used together with the <tt/.STRING/ builtin function. The function may + be used in any case where a string constant is expected. + + Example: + + <tscreen><verb> + .include .concat ("myheader", ".", "inc") + </verb></tscreen> + + This is the same as the command + + <tscreen><verb> + .include "myheader.inc" + </verb></tscreen> + + +<sect1><tt>.CONST</tt><label id=".CONST"><p> + + Builtin function. The function evaluates its argument in braces and + yields "true" if the argument is a constant expression (that is, an + expression that yields a constant value at assembly time) and "false" + otherwise. As an example, the .IFCONST statement may be replaced by + + <tscreen><verb> + .if .const(a + 3) + </verb></tscreen> + + +<sect1><tt>.HIBYTE</tt><label id=".HIBYTE"><p> + + The function returns the high byte (that is, bits 8-15) of its argument. + It works identical to the '>' operator. + + See: <tt><ref id=".LOBYTE" name=".LOBYTE"></tt>, + <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt> + + +<sect1><tt>.HIWORD</tt><label id=".HIWORD"><p> + + The function returns the high word (that is, bits 16-31) of its argument. + + See: <tt><ref id=".LOWORD" name=".LOWORD"></tt> + + +<sect1><tt>.IDENT</tt><label id=".IDENT"><p> + + The function expects a string as its argument, and converts this argument + into an identifier. If the string starts with the current <tt/<ref + id=".LOCALCHAR" name=".LOCALCHAR">/, it will be converted into a cheap local + identifier, otherwise it will be converted into a normal identifier. + + Example: + + <tscreen><verb> + .macro makelabel arg1, arg2 + .ident (.concat (arg1, arg2)): + .endmacro + + makelabel "foo", "bar" + + .word foobar ; Valid label + </verb></tscreen> + + +<sect1><tt>.LEFT</tt><label id=".LEFT"><p> + + Builtin function. Extracts the left part of a given token list. + + Syntax: + + <tscreen><verb> + .LEFT (<int expr>, <token list>) + </verb></tscreen> + + The first integer expression gives the number of tokens to extract from + the token list. The second argument is the token list itself. The token + list may optionally be enclosed into curly braces. This allows the + inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). + + Example: + + To check in a macro if the given argument has a '#' as first token + (immediate addressing mode), use something like this: + + <tscreen><verb> + .macro ldax arg + ... + .if (.match (.left (1, {arg}), #)) + + ; ldax called with immediate operand + ... + + .endif + ... + .endmacro + </verb></tscreen> + + See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT" + name=".RIGHT"></tt> builtin functions. + + +<sect1><tt>.LOBYTE</tt><label id=".LOBYTE"><p> + + The function returns the low byte (that is, bits 0-7) of its argument. + It works identical to the '<' operator. + + See: <tt><ref id=".HIBYTE" name=".HIBYTE"></tt>, + <tt><ref id=".BANKBYTE" name=".BANKBYTE"></tt> + + +<sect1><tt>.LOWORD</tt><label id=".LOWORD"><p> + + The function returns the low word (that is, bits 0-15) of its argument. + + See: <tt><ref id=".HIWORD" name=".HIWORD"></tt> + + +<sect1><tt>.MATCH</tt><label id=".MATCH"><p> + + Builtin function. Matches two token lists against each other. This is + most useful within macros, since macros are not stored as strings, but + as lists of tokens. + + The syntax is + + <tscreen><verb> + .MATCH(<token list #1>, <token list #2>) + </verb></tscreen> + + Both token list may contain arbitrary tokens with the exception of the + terminator token (comma resp. right parenthesis) and + + <itemize> + <item>end-of-line + <item>end-of-file + </itemize> + + The token lists may optionally be enclosed into curly braces. This allows + the inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). Often a macro parameter is used for any of + the token lists. + + Please note that the function does only compare tokens, not token + attributes. So any number is equal to any other number, regardless of the + actual value. The same is true for strings. If you need to compare tokens + <em/and/ token attributes, use the <tt><ref id=".XMATCH" + name=".XMATCH"></tt> function. + + Example: + + Assume the macro <tt/ASR/, that will shift right the accumulator by one, + while honoring the sign bit. The builtin processor instructions will allow + an optional "A" for accu addressing for instructions like <tt/ROL/ and + <tt/ROR/. We will use the <tt><ref id=".MATCH" name=".MATCH"></tt> function + to check for this and print and error for invalid calls. + + <tscreen><verb> + .macro asr arg + + .if (.not .blank(arg)) .and (.not .match ({arg}, a)) + .error "Syntax error" + .endif + + cmp #$80 ; Bit 7 into carry + lsr a ; Shift carry into bit 7 + + .endmacro + </verb></tscreen> + + The macro will only accept no arguments, or one argument that must be the + reserved keyword "A". + + See: <tt><ref id=".XMATCH" name=".XMATCH"></tt> + + +<sect1><tt>.MAX</tt><label id=".MAX"><p> + + Builtin function. The result is the larger of two values. + + The syntax is + + <tscreen><verb> + .MAX (<value #1>, <value #2>) + </verb></tscreen> + + Example: + + <tscreen><verb> + ; Reserve space for the larger of two data blocks + savearea: .max (.sizeof (foo), .sizeof (bar)) + </verb></tscreen> + + See: <tt><ref id=".MIN" name=".MIN"></tt> + + +<sect1><tt>.MID</tt><label id=".MID"><p> + + Builtin function. Takes a starting index, a count and a token list as + arguments. Will return part of the token list. + + Syntax: + + <tscreen><verb> + .MID (<int expr>, <int expr>, <token list>) + </verb></tscreen> + + The first integer expression gives the starting token in the list (the first + token has index 0). The second integer expression gives the number of tokens + to extract from the token list. The third argument is the token list itself. + The token list may optionally be enclosed into curly braces. This allows the + inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). + + Example: + + To check in a macro if the given argument has a '<tt/#/' as first token + (immediate addressing mode), use something like this: + + <tscreen><verb> + .macro ldax arg + ... + .if (.match (.mid (0, 1, {arg}), #)) + + ; ldax called with immediate operand + ... + + .endif + ... + .endmacro + </verb></tscreen> + + See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT" + name=".RIGHT"></tt> builtin functions. + + +<sect1><tt>.MIN</tt><label id=".MIN"><p> + + Builtin function. The result is the smaller of two values. + + The syntax is + + <tscreen><verb> + .MIN (<value #1>, <value #2>) + </verb></tscreen> + + Example: + + <tscreen><verb> + ; Reserve space for some data, but 256 bytes minimum + savearea: .min (.sizeof (foo), 256) + </verb></tscreen> + + See: <tt><ref id=".MAX" name=".MAX"></tt> + + +<sect1><tt>.REF, .REFERENCED</tt><label id=".REFERENCED"><p> + + Builtin function. The function expects an identifier as argument in braces. + The argument is evaluated, and the function yields "true" if the identifier + is a symbol that has already been referenced somewhere in the source file up + to the current position. Otherwise the function yields false. As an example, + the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by + + <tscreen><verb> + .if .referenced(a) + </verb></tscreen> + + See: <tt><ref id=".DEFINED" name=".DEFINED"></tt> + + +<sect1><tt>.RIGHT</tt><label id=".RIGHT"><p> + + Builtin function. Extracts the right part of a given token list. + + Syntax: + + <tscreen><verb> + .RIGHT (<int expr>, <token list>) + </verb></tscreen> + + The first integer expression gives the number of tokens to extract from the + token list. The second argument is the token list itself. The token list + may optionally be enclosed into curly braces. This allows the inclusion of + tokens that would otherwise terminate the list (the closing right paren in + the given case). + + See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".MID" + name=".MID"></tt> builtin functions. + + +<sect1><tt>.SIZEOF</tt><label id=".SIZEOF"><p> + + <tt/.SIZEOF/ is a pseudo function that returns the size of its argument. The + argument can be a struct/union, a struct member, a procedure, or a label. In + case of a procedure or label, its size is defined by the amount of data + placed in the segment where the label is relative to. If a line of code + switches segments (for example in a macro) data placed in other segments + does not count for the size. + + Please note that a symbol or scope must exist, before it is used together with + <tt/.SIZEOF/ (this may get relaxed later, but will always be true for scopes). + A scope has preference over a symbol with the same name, so if the last part + of a name represents both, a scope and a symbol, the scope is chosen over the + symbol. + + After the following code: + + <tscreen><verb> + .struct Point ; Struct size = 4 + xcoord .word + ycoord .word + .endstruct + + P: .tag Point ; Declare a point + @P: .tag Point ; Declare another point + + .code + .proc Code + nop + .proc Inner + nop + .endproc + nop + .endproc + + .proc Data + .data ; Segment switch!!! + .res 4 + .endproc + </verb></tscreen> + + <descrip> + <tag><tt/.sizeof(Point)/</tag> + will have the value 4, because this is the size of struct <tt/Point/. + + <tag><tt/.sizeof(Point::xcoord)/</tag> + will have the value 2, because this is the size of the member <tt/xcoord/ + in struct <tt/Point/. + + <tag><tt/.sizeof(P)/</tag> + will have the value 4, this is the size of the data declared on the same + source line as the label <tt/P/, which is in the same segment that <tt/P/ + is relative to. + + <tag><tt/.sizeof(@P)/</tag> + will have the value 4, see above. The example demonstrates that <tt/.SIZEOF/ + does also work for cheap local symbols. + + <tag><tt/.sizeof(Code)/</tag> + will have the value 3, since this is amount of data emitted into the code + segment, the segment that was active when <tt/Code/ was entered. Note that + this value includes the amount of data emitted in child scopes (in this + case <tt/Code::Inner/). + + <tag><tt/.sizeof(Code::Inner)/</tag> + will have the value 1 as expected. + + <tag><tt/.sizeof(Data)/</tag> + will have the value 0. Data is emitted within the scope <tt/Data/, but since + the segment is switched after entry, this data is emitted into another + segment. + </descrip> + + +<sect1><tt>.STRAT</tt><label id=".STRAT"><p> + + Builtin function. The function accepts a string and an index as + arguments and returns the value of the character at the given position + as an integer value. The index is zero based. + + Example: + + <tscreen><verb> + .macro M Arg + ; Check if the argument string starts with '#' + .if (.strat (Arg, 0) = '#') + ... + .endif + .endmacro + </verb></tscreen> + + +<sect1><tt>.SPRINTF</tt><label id=".SPRINTF"><p> + + Builtin function. It expects a format string as first argument. The number + and type of the following arguments depend on the format string. The format + string is similar to the one of the C <tt/printf/ function. Missing things + are: Length modifiers, variable width. + + The result of the function is a string. + + Example: + + <tscreen><verb> + num = 3 + + ; Generate an identifier: + .ident (.sprintf ("%s%03d", "label", num)): + </verb></tscreen> + + +<sect1><tt>.STRING</tt><label id=".STRING"><p> + + Builtin function. The function accepts an argument in braces and converts + this argument into a string constant. The argument may be an identifier, or + a constant numeric value. + + Since you can use a string in the first place, the use of the function may + not be obvious. However, it is useful in macros, or more complex setups. + + Example: + + <tscreen><verb> + ; Emulate other assemblers: + .macro section name + .segment .string(name) + .endmacro + </verb></tscreen> + + +<sect1><tt>.STRLEN</tt><label id=".STRLEN"><p> + + Builtin function. The function accepts a string argument in braces and + evaluates to the length of the string. + + Example: + + The following macro encodes a string as a pascal style string with + a leading length byte. + + <tscreen><verb> + .macro PString Arg + .byte .strlen(Arg), Arg + .endmacro + </verb></tscreen> + + +<sect1><tt>.TCOUNT</tt><label id=".TCOUNT"><p> + + Builtin function. The function accepts a token list in braces. The function + result is the number of tokens given as argument. The token list may + optionally be enclosed into curly braces which are not considered part of + the list and not counted. Enclosement in curly braces allows the inclusion + of tokens that would otherwise terminate the list (the closing right paren + in the given case). + + Example: + + The <tt/ldax/ macro accepts the '#' token to denote immediate addressing (as + with the normal 6502 instructions). To translate it into two separate 8 bit + load instructions, the '#' token has to get stripped from the argument: + + <tscreen><verb> + .macro ldax arg + .if (.match (.mid (0, 1, {arg}), #)) + ; ldax called with immediate operand + lda #<(.right (.tcount ({arg})-1, {arg})) + ldx #>(.right (.tcount ({arg})-1, {arg})) + .else + ... + .endif + .endmacro + </verb></tscreen> + + +<sect1><tt>.XMATCH</tt><label id=".XMATCH"><p> + + Builtin function. Matches two token lists against each other. This is + most useful within macros, since macros are not stored as strings, but + as lists of tokens. + + The syntax is + + <tscreen><verb> + .XMATCH(<token list #1>, <token list #2>) + </verb></tscreen> + + Both token list may contain arbitrary tokens with the exception of the + terminator token (comma resp. right parenthesis) and + + <itemize> + <item>end-of-line + <item>end-of-file + </itemize> + + The token lists may optionally be enclosed into curly braces. This allows + the inclusion of tokens that would otherwise terminate the list (the closing + right paren in the given case). Often a macro parameter is used for any of + the token lists. + + The function compares tokens <em/and/ token values. If you need a function + that just compares the type of tokens, have a look at the <tt><ref + id=".MATCH" name=".MATCH"></tt> function. + + See: <tt><ref id=".MATCH" name=".MATCH"></tt> + + + +<sect>Control commands<label id="control-commands"><p> + +Here's a list of all control commands and a description, what they do: + + +<sect1><tt>.A16</tt><label id=".A16"><p> + + Valid only in 65816 mode. Switch the accumulator to 16 bit. + + Note: This command will not emit any code, it will tell the assembler to + create 16 bit operands for immediate accumulator addressing mode. + + See also: <tt><ref id=".SMART" name=".SMART"></tt> + + +<sect1><tt>.A8</tt><label id=".A8"><p> + + Valid only in 65816 mode. Switch the accumulator to 8 bit. + + Note: This command will not emit any code, it will tell the assembler to + create 8 bit operands for immediate accu addressing mode. + + See also: <tt><ref id=".SMART" name=".SMART"></tt> + + +<sect1><tt>.ADDR</tt><label id=".ADDR"><p> + + Define word sized data. In 6502 mode, this is an alias for <tt/.WORD/ and + may be used for better readability if the data words are address values. In + 65816 mode, the address is forced to be 16 bit wide to fit into the current + segment. See also <tt><ref id=".FARADDR" name=".FARADDR"></tt>. The command + must be followed by a sequence of (not necessarily constant) expressions. + + Example: + + <tscreen><verb> + .addr $0D00, $AF13, _Clear + </verb></tscreen> + + See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD" + name=".WORD"></tt> + + +<sect1><tt>.ALIGN</tt><label id=".ALIGN"><p> + + Align data to a given boundary. The command expects a constant integer + argument in the range 1 ... 65536, plus an optional second argument + in byte range. If there is a second argument, it is used as fill value, + otherwise the value defined in the linker configuration file is used + (the default for this value is zero). + + <tt/.ALIGN/ will insert fill bytes, and the number of fill bytes depend of + the final address of the segment. <tt/.ALIGN/ cannot insert a variable + number of bytes, since that would break address calculations within the + module. So each <tt/.ALIGN/ expects the segment to be aligned to a multiple + of the alignment, because that allows the number of fill bytes to be + calculated in advance by the assembler. You are therefore required to + specify a matching alignment for the segment in the linker config. The + linker will output a warning if the alignment of the segment is less than + what is necessary to have a correct alignment in the object file. + + Example: + + <tscreen><verb> + .align 256 + </verb></tscreen> + + Some unexpected behaviour might occur if there are multiple <tt/.ALIGN/ + commands with different arguments. To allow the assembler to calculate the + number of fill bytes in advance, the alignment of the segment must be a + multiple of each of the alignment factors. This may result in unexpectedly + large alignments for the segment within the module. + + Example: + + <tscreen><verb> + .align 15 + .byte 15 + .align 18 + .byte 18 + </verb></tscreen> + + For the assembler to be able to align correctly, the segment must be aligned + to the least common multiple of 15 and 18 which is 90. The assembler will + calculate this automatically and will mark the segment with this value. + + Unfortunately, the combined alignment may get rather large without the user + knowing about it, wasting space in the final executable. If we add another + alignment to the example above + + <tscreen><verb> + .align 15 + .byte 15 + .align 18 + .byte 18 + .align 251 + .byte 0 + </verb></tscreen> + + the assembler will force a segment alignment to the least common multiple of + 15, 18 and 251 - which is 22590. To protect the user against errors, the + assembler will issue a warning when the combined alignment exceeds 256. The + command line option <tt><ref id="option--large-alignment" + name="--large-alignment"></tt> will disable this warning. + + Please note that with alignments that are a power of two (which were the + only alignments possible in older versions of the assembler), the problem is + less severe, because the least common multiple of powers to the same base is + always the larger one. + + + +<sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p> + + Define a string with a trailing zero. + + Example: + + <tscreen><verb> + Msg: .asciiz "Hello world" + </verb></tscreen> + + This will put the string "Hello world" followed by a binary zero into + the current segment. There may be more strings separated by commas, but + the binary zero is only appended once (after the last one). + + +<sect1><tt>.ASSERT</tt><label id=".ASSERT"><p> + + Add an assertion. The command is followed by an expression, an action + specifier, and an optional message that is output in case the assertion + fails. If no message was given, the string "Assertion failed" is used. The + action specifier may be one of <tt/warning/, <tt/error/, <tt/ldwarning/ or + <tt/lderror/. In the former two cases, the assertion is evaluated by the + assembler if possible, and in any case, it's also passed to the linker in + the object file (if one is generated). The linker will then evaluate the + expression when segment placement has been done. + + Example: + + <tscreen><verb> + .assert * = $8000, error, "Code not at $8000" + </verb></tscreen> + + The example assertion will check that the current location is at $8000, + when the output file is written, and abort with an error if this is not + the case. More complex expressions are possible. The action specifier + <tt/warning/ outputs a warning, while the <tt/error/ specifier outputs + an error message. In the latter case, generation of the output file is + suppressed in both the assembler and linker. + + +<sect1><tt>.AUTOIMPORT</tt><label id=".AUTOIMPORT"><p> + + Is followed by a plus or a minus character. When switched on (using a + +), undefined symbols are automatically marked as import instead of + giving errors. When switched off (which is the default so this does not + make much sense), this does not happen and an error message is + displayed. The state of the autoimport flag is evaluated when the + complete source was translated, before outputting actual code, so it is + <em/not/ possible to switch this feature on or off for separate sections + of code. The last setting is used for all symbols. + + You should probably not use this switch because it delays error + messages about undefined symbols until the link stage. The cc65 + compiler (which is supposed to produce correct assembler code in all + circumstances, something which is not true for most assembler + programmers) will insert this command to avoid importing each and every + routine from the runtime library. + + Example: + + <tscreen><verb> + .autoimport + ; Switch on auto import + </verb></tscreen> + +<sect1><tt>.BANKBYTES</tt><label id=".BANKBYTES"><p> + + Define byte sized data by extracting only the bank byte (that is, bits 16-23) from + each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with + the operator '^' prepended to each expression in its list. + + Example: + + <tscreen><verb> + .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 + + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable + TableLookupBank: .bankbytes MyTable + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + TableLookupBank: .byte ^TableItem0, ^TableItem1, ^TableItem2, ^TableItem3 + </verb></tscreen> + + See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, + <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>, + <tt><ref id=".LOBYTES" name=".LOBYTES"></tt> + + +<sect1><tt>.BSS</tt><label id=".BSS"><p> + + Switch to the BSS segment. The name of the BSS segment is always "BSS", + so this is a shortcut for + + <tscreen><verb> + .segment "BSS" + </verb></tscreen> + + See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. + + +<sect1><tt>.BYT, .BYTE</tt><label id=".BYTE"><p> + + Define byte sized data. Must be followed by a sequence of (byte ranged) + expressions or strings. + + Example: + + <tscreen><verb> + .byte "Hello " + .byt "world", $0D, $00 + </verb></tscreen> + + +<sect1><tt>.CASE</tt><label id=".CASE"><p> + + Switch on or off case sensitivity on identifiers. The default is off + (that is, identifiers are case sensitive), but may be changed by the + -i switch on the command line. + The command must be followed by a '+' or '-' character to switch the + option on or off respectively. + + Example: + + <tscreen><verb> + .case - ; Identifiers are not case sensitive + </verb></tscreen> + + +<sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p> + + Apply a custom mapping for characters. The command is followed by two + numbers. The first one is the index of the source character (range 1..255), + the second one is the mapping (range 0..255). The mapping applies to all + character and string constants when they generate output, and overrides a + mapping table specified with the <tt><ref id="option-t" name="-t"></tt> + command line switch. + + Example: + + <tscreen><verb> + .charmap $41, $61 ; Map 'A' to 'a' + </verb></tscreen> + + +<sect1><tt>.CODE</tt><label id=".CODE"><p> + + Switch to the CODE segment. The name of the CODE segment is always + "CODE", so this is a shortcut for + + <tscreen><verb> + .segment "CODE" + </verb></tscreen> + + See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. + + +<sect1><tt>.CONDES</tt><label id=".CONDES"><p> + + Export a symbol and mark it in a special way. The linker is able to build + tables of all such symbols. This may be used to automatically create a list + of functions needed to initialize linked library modules. + + Note: The linker has a feature to build a table of marked routines, but it + is your code that must call these routines, so just declaring a symbol with + <tt/.CONDES/ does nothing by itself. + + All symbols are exported as an absolute (16 bit) symbol. You don't need to + use an additional <tt><ref id=".EXPORT" name=".EXPORT"></tt> statement, this + is implied by <tt/.CONDES/. + + <tt/.CONDES/ is followed by the type, which may be <tt/constructor/, + <tt/destructor/ or a numeric value between 0 and 6 (where 0 is the same as + specifying <tt/constructor/ and 1 is equal to specifying <tt/destructor/). + The <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref + id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" + name=".INTERRUPTOR"></tt> commands are actually shortcuts for <tt/.CONDES/ + with a type of <tt/constructor/ resp. <tt/destructor/ or <tt/interruptor/. + + After the type, an optional priority may be specified. Higher numeric values + mean higher priority. If no priority is given, the default priority of 7 is + used. Be careful when assigning priorities to your own module constructors + so they won't interfere with the ones in the cc65 library. + + Example: + + <tscreen><verb> + .condes ModuleInit, constructor + .condes ModInit, 0, 16 + </verb></tscreen> + + See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref + id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" + name=".INTERRUPTOR"></tt> commands and the separate section <ref id="condes" + name="Module constructors/destructors"> explaining the feature in more + detail. + + +<sect1><tt>.CONSTRUCTOR</tt><label id=".CONSTRUCTOR"><p> + + Export a symbol and mark it as a module constructor. This may be used + together with the linker to build a table of constructor subroutines that + are called by the startup code. + + Note: The linker has a feature to build a table of marked routines, but it + is your code that must call these routines, so just declaring a symbol as + constructor does nothing by itself. + + A constructor is always exported as an absolute (16 bit) symbol. You don't + need to use an additional <tt/.export/ statement, this is implied by + <tt/.constructor/. It may have an optional priority that is separated by a + comma. Higher numeric values mean a higher priority. If no priority is + given, the default priority of 7 is used. Be careful when assigning + priorities to your own module constructors so they won't interfere with the + ones in the cc65 library. + + Example: + + <tscreen><verb> + .constructor ModuleInit + .constructor ModInit, 16 + </verb></tscreen> + + See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref + id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> commands and the separate section + <ref id="condes" name="Module constructors/destructors"> explaining the + feature in more detail. + + +<sect1><tt>.DATA</tt><label id=".DATA"><p> + + Switch to the DATA segment. The name of the DATA segment is always + "DATA", so this is a shortcut for + + <tscreen><verb> + .segment "DATA" + </verb></tscreen> + + See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. + + +<sect1><tt>.DBYT</tt><label id=".DBYT"><p> + + Define word sized data with the hi and lo bytes swapped (use <tt/.WORD/ to + create word sized data in native 65XX format). Must be followed by a + sequence of (word ranged) expressions. + + Example: + + <tscreen><verb> + .dbyt $1234, $4512 + </verb></tscreen> + + This will emit the bytes + + <tscreen><verb> + $12 $34 $45 $12 + </verb></tscreen> + + into the current segment in that order. + + +<sect1><tt>.DEBUGINFO</tt><label id=".DEBUGINFO"><p> + + Switch on or off debug info generation. The default is off (that is, + the object file will not contain debug infos), but may be changed by the + -g switch on the command line. + The command must be followed by a '+' or '-' character to switch the + option on or off respectively. + + Example: + + <tscreen><verb> + .debuginfo + ; Generate debug info + </verb></tscreen> + + +<sect1><tt>.DEFINE</tt><label id=".DEFINE"><p> + + Start a define style macro definition. The command is followed by an + identifier (the macro name) and optionally by a list of formal arguments + in braces. + + Please note that <tt/.DEFINE/ shares most disadvantages with its C + counterpart, so the general advice is, <bf/NOT/ do use <tt/.DEFINE/ if you + don't have to. + + See also the <tt><ref id=".UNDEFINE" name=".UNDEFINE"></tt> command and + section <ref id="macros" name="Macros">. + + +<sect1><tt>.DELMAC, .DELMACRO</tt><label id=".DELMACRO"><p> + + Delete a classic macro (defined with <tt><ref id=".MACRO" + name=".MACRO"></tt>) . The command is followed by the name of an + existing macro. Its definition will be deleted together with the name. + If necessary, another macro with this name may be defined later. + + See: <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, + <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>, + <tt><ref id=".MACRO" name=".MACRO"></tt> + + See also section <ref id="macros" name="Macros">. + + +<sect1><tt>.DEF, .DEFINED</tt><label id=".DEFINED"><p> + + Builtin function. The function expects an identifier as argument in braces. + The argument is evaluated, and the function yields "true" if the identifier + is a symbol that is already defined somewhere in the source file up to the + current position. Otherwise the function yields false. As an example, the + <tt><ref id=".IFDEF" name=".IFDEF"></tt> statement may be replaced by + + <tscreen><verb> + .if .defined(a) + </verb></tscreen> + + +<sect1><tt>.DESTRUCTOR</tt><label id=".DESTRUCTOR"><p> + + Export a symbol and mark it as a module destructor. This may be used + together with the linker to build a table of destructor subroutines that + are called by the startup code. + + Note: The linker has a feature to build a table of marked routines, but it + is your code that must call these routines, so just declaring a symbol as + constructor does nothing by itself. + + A destructor is always exported as an absolute (16 bit) symbol. You don't + need to use an additional <tt/.export/ statement, this is implied by + <tt/.destructor/. It may have an optional priority that is separated by a + comma. Higher numerical values mean a higher priority. If no priority is + given, the default priority of 7 is used. Be careful when assigning + priorities to your own module destructors so they won't interfere with the + ones in the cc65 library. + + Example: + + <tscreen><verb> + .destructor ModuleDone + .destructor ModDone, 16 + </verb></tscreen> + + See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref + id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt> commands and the separate + section <ref id="condes" name="Module constructors/destructors"> explaining + the feature in more detail. + + +<sect1><tt>.DWORD</tt><label id=".DWORD"><p> + + Define dword sized data (4 bytes) Must be followed by a sequence of + expressions. + + Example: + + <tscreen><verb> + .dword $12344512, $12FA489 + </verb></tscreen> + + +<sect1><tt>.ELSE</tt><label id=".ELSE"><p> + + Conditional assembly: Reverse the current condition. + + +<sect1><tt>.ELSEIF</tt><label id=".ELSEIF"><p> + + Conditional assembly: Reverse current condition and test a new one. + + +<sect1><tt>.END</tt><label id=".END"><p> + + Forced end of assembly. Assembly stops at this point, even if the command + is read from an include file. + + +<sect1><tt>.ENDENUM</tt><label id=".ENDENUM"><p> + + End a <tt><ref id=".ENUM" name=".ENUM"></tt> declaration. + + +<sect1><tt>.ENDIF</tt><label id=".ENDIF"><p> + + Conditional assembly: Close a <tt><ref id=".IF" name=".IF..."></tt> or + <tt><ref id=".ELSE" name=".ELSE"></tt> branch. + + +<sect1><tt>.ENDMAC, .ENDMACRO</tt><label id=".ENDMACRO"><p> + + Marks the end of a macro definition. + + See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, + <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>, + <tt><ref id=".MACRO" name=".MACRO"></tt> + + See also section <ref id="macros" name="Macros">. + + +<sect1><tt>.ENDPROC</tt><label id=".ENDPROC"><p> + + End of local lexical level (see <tt><ref id=".PROC" name=".PROC"></tt>). + + +<sect1><tt>.ENDREP, .ENDREPEAT</tt><label id=".ENDREPEAT"><p> + + End a <tt><ref id=".REPEAT" name=".REPEAT"></tt> block. + + +<sect1><tt>.ENDSCOPE</tt><label id=".ENDSCOPE"><p> + + End of local lexical level (see <tt/<ref id=".SCOPE" name=".SCOPE">/). + + +<sect1><tt>.ENDSTRUCT</tt><label id=".ENDSTRUCT"><p> + + Ends a struct definition. See the <tt/<ref id=".STRUCT" name=".STRUCT">/ + command and the separate section named <ref id="structs" name=""Structs + and unions"">. + + +<sect1><tt>.ENDUNION</tt><label id=".ENDUNION"><p> + + Ends a union definition. See the <tt/<ref id=".UNION" name=".UNION">/ + command and the separate section named <ref id="structs" name=""Structs + and unions"">. + + +<sect1><tt>.ENUM</tt><label id=".ENUM"><p> + + Start an enumeration. This directive is very similar to the C <tt/enum/ + keyword. If a name is given, a new scope is created for the enumeration, + otherwise the enumeration members are placed in the enclosing scope. + + In the enumeration body, symbols are declared. The first symbol has a value + of zero, and each following symbol will get the value of the preceding plus + one. This behaviour may be overridden by an explicit assignment. Two symbols + may have the same value. + + Example: + + <tscreen><verb> + .enum errorcodes + no_error + file_error + parse_error + .endenum + </verb></tscreen> + + Above example will create a new scope named <tt/errorcodes/ with three + symbols in it that get the values 0, 1 and 2 respectively. Another way + to write this would have been: + + <tscreen><verb> + .scope errorcodes + no_error = 0 + file_error = 1 + parse_error = 2 + .endscope + </verb></tscreen> + + Please note that explicit scoping must be used to access the identifiers: + + <tscreen><verb> + .word errorcodes::no_error + </verb></tscreen> + + A more complex example: + + <tscreen><verb> + .enum + EUNKNOWN = -1 + EOK + EFILE + EBUSY + EAGAIN + EWOULDBLOCK = EAGAIN + .endenum + </verb></tscreen> + + In this example, the enumeration does not have a name, which means that the + members will be visible in the enclosing scope and can be used in this scope + without explicit scoping. The first member (<tt/EUNKNOWN/) has the value -1. + The value for the following members is incremented by one, so <tt/EOK/ would + be zero and so on. <tt/EWOULDBLOCK/ is an alias for <tt/EGAIN/, so it has an + override for the value using an already defined symbol. + + +<sect1><tt>.ERROR</tt><label id=".ERROR"><p> + + Force an assembly error. The assembler will output an error message + preceded by "User error". Assembly is continued but no object file will + generated. + + This command may be used to check for initial conditions that must be + set before assembling a source file. + + Example: + + <tscreen><verb> + .if foo = 1 + ... + .elseif bar = 1 + ... + .else + .error "Must define foo or bar!" + .endif + </verb></tscreen> + + See also: <tt><ref id=".FATAL" name=".FATAL"></tt>, + <tt><ref id=".OUT" name=".OUT"></tt>, + <tt><ref id=".WARNING" name=".WARNING"></tt> + + +<sect1><tt>.EXITMAC, .EXITMACRO</tt><label id=".EXITMACRO"><p> + + Abort a macro expansion immediately. This command is often useful in + recursive macros. + + See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, + <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, + <tt><ref id=".MACRO" name=".MACRO"></tt> + + See also section <ref id="macros" name="Macros">. + + +<sect1><tt>.EXPORT</tt><label id=".EXPORT"><p> + + Make symbols accessible from other modules. Must be followed by a comma + separated list of symbols to export, with each one optionally followed by an + address specification and (also optional) an assignment. Using an additional + assignment in the export statement allows to define and export a symbol in + one statement. The default is to export the symbol with the address size it + actually has. The assembler will issue a warning, if the symbol is exported + with an address size smaller than the actual address size. + + Examples: + + <tscreen><verb> + .export foo + .export bar: far + .export foobar: far = foo * bar + .export baz := foobar, zap: far = baz - bar + </verb></tscreen> + + As with constant definitions, using <tt/:=/ instead of <tt/=/ marks the + symbols as a label. + + See: <tt><ref id=".EXPORTZP" name=".EXPORTZP"></tt> + + +<sect1><tt>.EXPORTZP</tt><label id=".EXPORTZP"><p> + + Make symbols accessible from other modules. Must be followed by a comma + separated list of symbols to export. The exported symbols are explicitly + marked as zero page symbols. An assignment may be included in the + <tt/.EXPORTZP/ statement. This allows to define and export a symbol in one + statement. + + Examples: + + <tscreen><verb> + .exportzp foo, bar + .exportzp baz := $02 + </verb></tscreen> + + See: <tt><ref id=".EXPORT" name=".EXPORT"></tt> + + +<sect1><tt>.FARADDR</tt><label id=".FARADDR"><p> + + Define far (24 bit) address data. The command must be followed by a + sequence of (not necessarily constant) expressions. + + Example: + + <tscreen><verb> + .faraddr DrawCircle, DrawRectangle, DrawHexagon + </verb></tscreen> + + See: <tt><ref id=".ADDR" name=".ADDR"></tt> + + +<sect1><tt>.FATAL</tt><label id=".FATAL"><p> + + Force an assembly error and terminate assembly. The assembler will output an + error message preceded by "User error" and will terminate assembly + immediately. + + This command may be used to check for initial conditions that must be + set before assembling a source file. + + Example: + + <tscreen><verb> + .if foo = 1 + ... + .elseif bar = 1 + ... + .else + .fatal "Must define foo or bar!" + .endif + </verb></tscreen> + + See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, + <tt><ref id=".OUT" name=".OUT"></tt>, + <tt><ref id=".WARNING" name=".WARNING"></tt> + + +<sect1><tt>.FEATURE</tt><label id=".FEATURE"><p> + + This directive may be used to enable one or more compatibility features + of the assembler. While the use of <tt/.FEATURE/ should be avoided when + possible, it may be useful when porting sources written for other + assemblers. There is no way to switch a feature off, once you have + enabled it, so using + + <tscreen><verb> + .FEATURE xxx + </verb></tscreen> + + will enable the feature until end of assembly is reached. + + The following features are available: + + <descrip> + + <tag><tt>at_in_identifiers</tt><label id="at_in_identifiers"></tag> + + Accept the at character (`@') as a valid character in identifiers. The + at character is not allowed to start an identifier, even with this + feature enabled. + + <tag><tt>c_comments</tt><label id="c_comments"></tag> + + Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right + comment terminators. Note that C comments may not be nested. There's also a + pitfall when using C like comments: All statements must be terminated by + "end-of-line". Using C like comments, it is possible to hide the newline, + which results in error messages. See the following non working example: + + <tscreen><verb> + lda #$00 /* This comment hides the newline +*/ sta $82 + </verb></tscreen> + + <tag><tt>dollar_in_identifiers</tt><label id="dollar_in_identifiers"></tag> + + Accept the dollar sign (`$') as a valid character in identifiers. The + dollar character is not allowed to start an identifier, even with this + feature enabled. + + <tag><tt>dollar_is_pc</tt><label id="dollar_is_pc"></tag> + + The dollar sign may be used as an alias for the star (`*'), which + gives the value of the current PC in expressions. + Note: Assignment to the pseudo variable is not allowed. + + <tag><tt>force_range</tt><label id="force_range"></tag> + + Force expressions into their valid range for immediate addressing and + storage operators like <tt><ref id=".BYTE" name=".BYTE"></tt> and + <tt><ref id=".WORD" name=".WORD"></tt>. Be very careful with this one, + since it will completely disable error checks. + + <tag><tt>labels_without_colons</tt><label id="labels_without_colons"></tag> + + Allow labels without a trailing colon. These labels are only accepted, + if they start at the beginning of a line (no leading white space). + + <tag><tt>leading_dot_in_identifiers</tt><label id="leading_dot_in_identifiers"></tag> + + Accept the dot (`.') as the first character of an identifier. This may be + used for example to create macro names that start with a dot emulating + control directives of other assemblers. Note however, that none of the + reserved keywords built into the assembler, that starts with a dot, may be + overridden. When using this feature, you may also get into trouble if + later versions of the assembler define new keywords starting with a dot. + + <tag><tt>loose_char_term</tt><label id="loose_char_term"></tag> + + Accept single quotes as well as double quotes as terminators for char + constants. + + <tag><tt>loose_string_term</tt><label id="loose_string_term"></tag> + + Accept single quotes as well as double quotes as terminators for string + constants. + + <tag><tt>missing_char_term</tt><label id="missing_char_term"></tag> + + Accept single quoted character constants where the terminating quote is + missing. + <tscreen><verb> + lda #'a + </verb></tscreen> + <bf/Note:/ This does not work in conjunction with <tt/.FEATURE + loose_string_term/, since in this case the input would be ambiguous. + + <tag><tt>org_per_seg</tt><label id="org_per_seg"></tag> + + This feature makes relocatable/absolute mode local to the current segment. + Using <tt><ref id=".ORG" name=".ORG"></tt> when <tt/org_per_seg/ is in + effect will only enable absolute mode for the current segment. Dito for + <tt><ref id=".RELOC" name=".RELOC"></tt>. + + <tag><tt>pc_assignment</tt><label id="pc_assignment"></tag> + + Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/ + is enabled). Such an assignment is handled identical to the <tt><ref + id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just + removing the lines with the assignments may also be an option when porting + code written for older assemblers). + + <tag><tt>ubiquitous_idents</tt><label id="ubiquitous_idents"></tag> + + Allow the use of instructions names as names for macros and symbols. This + makes it possible to "overload" instructions by defining a macro with the + same name. This does also make it possible to introduce hard to find errors + in your code, so be careful! + + <tag><tt>underline_in_numbers</tt><label id="underline_in_numbers"></tag> + + Allow underlines within numeric constants. These may be used for grouping + the digits of numbers for easier reading. + Example: + <tscreen><verb> + .feature underline_in_numbers + .word %1100001110100101 + .word %1100_0011_1010_0101 ; Identical but easier to read + </verb></tscreen> + + </descrip> + + It is also possible to specify features on the command line using the + <tt><ref id="option--feature" name="--feature"></tt> command line option. + This is useful when translating sources written for older assemblers, when + you don't want to change the source code. + + As an example, to translate sources written for Andre Fachats xa65 + assembler, the features + + <verb> + labels_without_colons, pc_assignment, loose_char_term + </verb> + + may be helpful. They do not make ca65 completely compatible, so you may not + be able to translate the sources without changes, even when enabling these + features. However, I have found several sources that translate without + problems when enabling these features on the command line. + + +<sect1><tt>.FILEOPT, .FOPT</tt><label id=".FOPT"><p> + + Insert an option string into the object file. There are two forms of + this command, one specifies the option by a keyword, the second + specifies it as a number. Since usage of the second one needs knowledge + of the internal encoding, its use is not recommended and I will only + describe the first form here. + + The command is followed by one of the keywords + + <tscreen><verb> + author + comment + compiler + </verb></tscreen> + + a comma and a string. The option is written into the object file + together with the string value. This is currently unidirectional and + there is no way to actually use these options once they are in the + object file. + + Examples: + + <tscreen><verb> + .fileopt comment, "Code stolen from my brother" + .fileopt compiler, "BASIC 2.0" + .fopt author, "J. R. User" + </verb></tscreen> + + +<sect1><tt>.FORCEIMPORT</tt><label id=".FORCEIMPORT"><p> + + Import an absolute symbol from another module. The command is followed by a + comma separated list of symbols to import. The command is similar to <tt> + <ref id=".IMPORT" name=".IMPORT"></tt>, but the import reference is always + written to the generated object file, even if the symbol is never referenced + (<tt><ref id=".IMPORT" name=".IMPORT"></tt> will not generate import + references for unused symbols). + + Example: + + <tscreen><verb> + .forceimport needthisone, needthistoo + </verb></tscreen> + + See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> + + +<sect1><tt>.GLOBAL</tt><label id=".GLOBAL"><p> + + Declare symbols as global. Must be followed by a comma separated list of + symbols to declare. Symbols from the list, that are defined somewhere in the + source, are exported, all others are imported. Additional <tt><ref + id=".IMPORT" name=".IMPORT"></tt> or <tt><ref id=".EXPORT" + name=".EXPORT"></tt> commands for the same symbol are allowed. + + Example: + + <tscreen><verb> + .global foo, bar + </verb></tscreen> + + +<sect1><tt>.GLOBALZP</tt><label id=".GLOBALZP"><p> + + Declare symbols as global. Must be followed by a comma separated list of + symbols to declare. Symbols from the list, that are defined somewhere in the + source, are exported, all others are imported. Additional <tt><ref + id=".IMPORTZP" name=".IMPORTZP"></tt> or <tt><ref id=".EXPORTZP" + name=".EXPORTZP"></tt> commands for the same symbol are allowed. The symbols + in the list are explicitly marked as zero page symbols. + + Example: + + <tscreen><verb> + .globalzp foo, bar + </verb></tscreen> + +<sect1><tt>.HIBYTES</tt><label id=".HIBYTES"><p> + + Define byte sized data by extracting only the high byte (that is, bits 8-15) from + each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with + the operator '>' prepended to each expression in its list. + + Example: + + <tscreen><verb> + .lobytes $1234, $2345, $3456, $4567 + .hibytes $fedc, $edcb, $dcba, $cba9 + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + .byte $34, $45, $56, $67 + .byte $fe, $ed, $dc, $cb + </verb></tscreen> + + Example: + + <tscreen><verb> + .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 + + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + </verb></tscreen> + + See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, + <tt><ref id=".LOBYTES" name=".LOBYTES"></tt>, + <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt> + + +<sect1><tt>.I16</tt><label id=".I16"><p> + + Valid only in 65816 mode. Switch the index registers to 16 bit. + + Note: This command will not emit any code, it will tell the assembler to + create 16 bit operands for immediate operands. + + See also the <tt><ref id=".I8" name=".I8"></tt> and <tt><ref id=".SMART" + name=".SMART"></tt> commands. + + +<sect1><tt>.I8</tt><label id=".I8"><p> + + Valid only in 65816 mode. Switch the index registers to 8 bit. + + Note: This command will not emit any code, it will tell the assembler to + create 8 bit operands for immediate operands. + + See also the <tt><ref id=".I16" name=".I16"></tt> and <tt><ref id=".SMART" + name=".SMART"></tt> commands. + + +<sect1><tt>.IF</tt><label id=".IF"><p> + + Conditional assembly: Evaluate an expression and switch assembler output + on or off depending on the expression. The expression must be a constant + expression, that is, all operands must be defined. + + A expression value of zero evaluates to FALSE, any other value evaluates + to TRUE. + + +<sect1><tt>.IFBLANK</tt><label id=".IFBLANK"><p> + + Conditional assembly: Check if there are any remaining tokens in this line, + and evaluate to FALSE if this is the case, and to TRUE otherwise. If the + condition is not true, further lines are not assembled until an <tt><ref + id=".ELSE" name=".ESLE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or + <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. + + This command is often used to check if a macro parameter was given. Since an + empty macro parameter will evaluate to nothing, the condition will evaluate + to TRUE if an empty parameter was given. + + Example: + + <tscreen><verb> + .macro arg1, arg2 + .ifblank arg2 + lda #arg1 + .else + lda #arg2 + .endif + .endmacro + </verb></tscreen> + + See also: <tt><ref id=".BLANK" name=".BLANK"></tt> + + +<sect1><tt>.IFCONST</tt><label id=".IFCONST"><p> + + Conditional assembly: Evaluate an expression and switch assembler output + on or off depending on the constness of the expression. + + A const expression evaluates to to TRUE, a non const expression (one + containing an imported or currently undefined symbol) evaluates to + FALSE. + + See also: <tt><ref id=".CONST" name=".CONST"></tt> + + +<sect1><tt>.IFDEF</tt><label id=".IFDEF"><p> + + Conditional assembly: Check if a symbol is defined. Must be followed by + a symbol name. The condition is true if the the given symbol is already + defined, and false otherwise. + + See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt> + + +<sect1><tt>.IFNBLANK</tt><label id=".IFNBLANK"><p> + + Conditional assembly: Check if there are any remaining tokens in this line, + and evaluate to TRUE if this is the case, and to FALSE otherwise. If the + condition is not true, further lines are not assembled until an <tt><ref + id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or + <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. + + This command is often used to check if a macro parameter was given. + Since an empty macro parameter will evaluate to nothing, the condition + will evaluate to FALSE if an empty parameter was given. + + Example: + + <tscreen><verb> + .macro arg1, arg2 + lda #arg1 + .ifnblank arg2 + lda #arg2 + .endif + .endmacro + </verb></tscreen> + + See also: <tt><ref id=".BLANK" name=".BLANK"></tt> + + +<sect1><tt>.IFNDEF</tt><label id=".IFNDEF"><p> + + Conditional assembly: Check if a symbol is defined. Must be followed by + a symbol name. The condition is true if the the given symbol is not + defined, and false otherwise. + + See also: <tt><ref id=".DEFINED" name=".DEFINED"></tt> + + +<sect1><tt>.IFNREF</tt><label id=".IFNREF"><p> + + Conditional assembly: Check if a symbol is referenced. Must be followed + by a symbol name. The condition is true if if the the given symbol was + not referenced before, and false otherwise. + + See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> + + +<sect1><tt>.IFP02</tt><label id=".IFP02"><p> + + Conditional assembly: Check if the assembler is currently in 6502 mode + (see <tt><ref id=".P02" name=".P02"></tt> command). + + +<sect1><tt>.IFP816</tt><label id=".IFP816"><p> + + Conditional assembly: Check if the assembler is currently in 65816 mode + (see <tt><ref id=".P816" name=".P816"></tt> command). + + +<sect1><tt>.IFPC02</tt><label id=".IFPC02"><p> + + Conditional assembly: Check if the assembler is currently in 65C02 mode + (see <tt><ref id=".PC02" name=".PC02"></tt> command). + + +<sect1><tt>.IFPSC02</tt><label id=".IFPSC02"><p> + + Conditional assembly: Check if the assembler is currently in 65SC02 mode + (see <tt><ref id=".PSC02" name=".PSC02"></tt> command). + + +<sect1><tt>.IFREF</tt><label id=".IFREF"><p> + + Conditional assembly: Check if a symbol is referenced. Must be followed + by a symbol name. The condition is true if if the the given symbol was + referenced before, and false otherwise. + + This command may be used to build subroutine libraries in include files + (you may use separate object modules for this purpose too). + + Example: + + <tscreen><verb> + .ifref ToHex ; If someone used this subroutine + ToHex: tay ; Define subroutine + lda HexTab,y + rts + .endif + </verb></tscreen> + + See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> + + +<sect1><tt>.IMPORT</tt><label id=".IMPORT"><p> + + Import a symbol from another module. The command is followed by a comma + separated list of symbols to import, with each one optionally followed by + an address specification. + + Example: + + <tscreen><verb> + .import foo + .import bar: zeropage + </verb></tscreen> + + See: <tt><ref id=".IMPORTZP" name=".IMPORTZP"></tt> + + +<sect1><tt>.IMPORTZP</tt><label id=".IMPORTZP"><p> + + Import a symbol from another module. The command is followed by a comma + separated list of symbols to import. The symbols are explicitly imported + as zero page symbols (that is, symbols with values in byte range). + + Example: + + <tscreen><verb> + .importzp foo, bar + </verb></tscreen> + + See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> + + +<sect1><tt>.INCBIN</tt><label id=".INCBIN"><p> + + Include a file as binary data. The command expects a string argument + that is the name of a file to include literally in the current segment. + In addition to that, a start offset and a size value may be specified, + separated by commas. If no size is specified, all of the file from the + start offset to end-of-file is used. If no start position is specified + either, zero is assumed (which means that the whole file is inserted). + + Example: + + <tscreen><verb> + ; Include whole file + .incbin "sprites.dat" + + ; Include file starting at offset 256 + .incbin "music.dat", $100 + + ; Read 100 bytes starting at offset 200 + .incbin "graphics.dat", 200, 100 + </verb></tscreen> + + +<sect1><tt>.INCLUDE</tt><label id=".INCLUDE"><p> + + Include another file. Include files may be nested up to a depth of 16. + + Example: + + <tscreen><verb> + .include "subs.inc" + </verb></tscreen> + + +<sect1><tt>.INTERRUPTOR</tt><label id=".INTERRUPTOR"><p> + + Export a symbol and mark it as an interruptor. This may be used together + with the linker to build a table of interruptor subroutines that are called + in an interrupt. + + Note: The linker has a feature to build a table of marked routines, but it + is your code that must call these routines, so just declaring a symbol as + interruptor does nothing by itself. + + An interruptor is always exported as an absolute (16 bit) symbol. You don't + need to use an additional <tt/.export/ statement, this is implied by + <tt/.interruptor/. It may have an optional priority that is separated by a + comma. Higher numeric values mean a higher priority. If no priority is + given, the default priority of 7 is used. Be careful when assigning + priorities to your own module constructors so they won't interfere with the + ones in the cc65 library. + + Example: + + <tscreen><verb> + .interruptor IrqHandler + .interruptor Handler, 16 + </verb></tscreen> + + See the <tt><ref id=".CONDES" name=".CONDES"></tt> command and the separate + section <ref id="condes" name="Module constructors/destructors"> explaining + the feature in more detail. + + +<sect1><tt>.LINECONT</tt><label id=".LINECONT"><p> + + Switch on or off line continuations using the backslash character + before a newline. The option is off by default. + Note: Line continuations do not work in a comment. A backslash at the + end of a comment is treated as part of the comment and does not trigger + line continuation. + The command must be followed by a '+' or '-' character to switch the + option on or off respectively. + + Example: + + <tscreen><verb> + .linecont + ; Allow line continuations + + lda \ + #$20 ; This is legal now + </verb></tscreen> + + +<sect1><tt>.LIST</tt><label id=".LIST"><p> + + Enable output to the listing. The command must be followed by a boolean + switch ("on", "off", "+" or "-") and will enable or disable listing + output. + The option has no effect if the listing is not enabled by the command line + switch -l. If -l is used, an internal counter is set to 1. Lines are output + to the listing file, if the counter is greater than zero, and suppressed if + the counter is zero. Each use of <tt/.LIST/ will increment or decrement the + counter. + + Example: + + <tscreen><verb> + .list on ; Enable listing output + </verb></tscreen> + + +<sect1><tt>.LISTBYTES</tt><label id=".LISTBYTES"><p> + + Set, how many bytes are shown in the listing for one source line. The + default is 12, so the listing will show only the first 12 bytes for any + source line that generates more than 12 bytes of code or data. + The directive needs an argument, which is either "unlimited", or an + integer constant in the range 4..255. + + Examples: + + <tscreen><verb> + .listbytes unlimited ; List all bytes + .listbytes 12 ; List the first 12 bytes + .incbin "data.bin" ; Include large binary file + </verb></tscreen> + + +<sect1><tt>.LOBYTES</tt><label id=".LOBYTES"><p> + + Define byte sized data by extracting only the low byte (that is, bits 0-7) from + each expression. This is equivalent to <tt><ref id=".BYTE" name=".BYTE"></tt> with + the operator '<' prepended to each expression in its list. + + Example: + + <tscreen><verb> + .lobytes $1234, $2345, $3456, $4567 + .hibytes $fedc, $edcb, $dcba, $cba9 + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + .byte $34, $45, $56, $67 + .byte $fe, $ed, $dc, $cb + </verb></tscreen> + + Example: + + <tscreen><verb> + .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 + + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable + </verb></tscreen> + + which is equivalent to + + <tscreen><verb> + TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + </verb></tscreen> + + See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, + <tt><ref id=".HIBYTES" name=".HIBYTES"></tt>, + <tt><ref id=".BANKBYTES" name=".BANKBYTES"></tt> + + +<sect1><tt>.LOCAL</tt><label id=".LOCAL"><p> + + This command may only be used inside a macro definition. It declares a + list of identifiers as local to the macro expansion. + + A problem when using macros are labels: Since they don't change their name, + you get a "duplicate symbol" error if the macro is expanded the second time. + Labels declared with <tt><ref id=".LOCAL" name=".LOCAL"></tt> have their + name mapped to an internal unique name (<tt/___ABCD__/) with each macro + invocation. + + Some other assemblers start a new lexical block inside a macro expansion. + This has some drawbacks however, since that will not allow <em/any/ symbol + to be visible outside a macro, a feature that is sometimes useful. The + <tt><ref id=".LOCAL" name=".LOCAL"></tt> command is in my eyes a better way + to address the problem. + + You get an error when using <tt><ref id=".LOCAL" name=".LOCAL"></tt> outside + a macro. + + +<sect1><tt>.LOCALCHAR</tt><label id=".LOCALCHAR"><p> + + Defines the character that start "cheap" local labels. You may use one + of '@' and '?' as start character. The default is '@'. + + Cheap local labels are labels that are visible only between two non + cheap labels. This way you can reuse identifiers like "<tt/loop/" without + using explicit lexical nesting. + + Example: + + <tscreen><verb> + .localchar '?' + + Clear: lda #$00 ; Global label + ?Loop: sta Mem,y ; Local label + dey + bne ?Loop ; Ok + rts + Sub: ... ; New global label + bne ?Loop ; ERROR: Unknown identifier! + </verb></tscreen> + + +<sect1><tt>.MACPACK</tt><label id=".MACPACK"><p> + + Insert a predefined macro package. The command is followed by an + identifier specifying the macro package to insert. Available macro + packages are: + + <tscreen><verb> + atari Defines the scrcode macro. + cbm Defines the scrcode macro. + cpu Defines constants for the .CPU variable. + generic Defines generic macros like add and sub. + longbranch Defines conditional long jump macros. + </verb></tscreen> + + Including a macro package twice, or including a macro package that + redefines already existing macros will lead to an error. + + Example: + + <tscreen><verb> + .macpack longbranch ; Include macro package + + cmp #$20 ; Set condition codes + jne Label ; Jump long on condition + </verb></tscreen> + + Macro packages are explained in more detail in section <ref + id="macropackages" name="Macro packages">. + + +<sect1><tt>.MAC, .MACRO</tt><label id=".MACRO"><p> + + Start a classic macro definition. The command is followed by an identifier + (the macro name) and optionally by a comma separated list of identifiers + that are macro parameters. A macro definition is terminated by <tt><ref + id=".ENDMACRO" name=".ENDMACRO"></tt>. + + Example: + + <tscreen><verb> + .macro ldax arg ; Define macro ldax + lda arg + ldx arg+1 + </verb></tscreen> + + See: <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, + <tt><ref id=".ENDMACRO" name=".ENDMACRO"></tt>, + <tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt> + + See also section <ref id="macros" name="Macros">. + + +<sect1><tt>.ORG</tt><label id=".ORG"><p> + + Start a section of absolute code. The command is followed by a constant + expression that gives the new PC counter location for which the code is + assembled. Use <tt><ref id=".RELOC" name=".RELOC"></tt> to switch back to + relocatable code. + + By default, absolute/relocatable mode is global (valid even when switching + segments). Using <tt>.FEATURE <ref id="org_per_seg" name="org_per_seg"></tt> + it can be made segment local. + + Please note that you <em/do not need/ <tt/.ORG/ in most cases. Placing + code at a specific address is the job of the linker, not the assembler, so + there is usually no reason to assemble code to a specific address. + + Example: + + <tscreen><verb> + .org $7FF ; Emit code starting at $7FF + </verb></tscreen> + + +<sect1><tt>.OUT</tt><label id=".OUT"><p> + + Output a string to the console without producing an error. This command + is similar to <tt/.ERROR/, however, it does not force an assembler error + that prevents the creation of an object file. + + Example: + + <tscreen><verb> + .out "This code was written by the codebuster(tm)" + </verb></tscreen> + + See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, + <tt><ref id=".FATAL" name=".FATAL"></tt>, + <tt><ref id=".WARNING" name=".WARNING"></tt> + + +<sect1><tt>.P02</tt><label id=".P02"><p> + + Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816 + instructions. This is the default if not overridden by the + <tt><ref id="option--cpu" name="--cpu"></tt> command line option. + + See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + + +<sect1><tt>.P816</tt><label id=".P816"><p> + + Enable the 65816 instruction set. This is a superset of the 65SC02 and + 6502 instruction sets. + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt> and <tt><ref id=".PC02" name=".PC02"></tt> + + +<sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p> + + Set the page length for the listing. Must be followed by an integer + constant. The value may be "unlimited", or in the range 32 to 127. The + statement has no effect if no listing is generated. The default value is -1 + (unlimited) but may be overridden by the <tt/--pagelength/ command line + option. Beware: Since ca65 is a one pass assembler, the listing is generated + after assembly is complete, you cannot use multiple line lengths with one + source. Instead, the value set with the last <tt/.PAGELENGTH/ is used. + + Examples: + + <tscreen><verb> + .pagelength 66 ; Use 66 lines per listing page + + .pagelength unlimited ; Unlimited page length + </verb></tscreen> + + +<sect1><tt>.PC02</tt><label id=".PC02"><p> + + Enable the 65C02 instructions set. This instruction set includes all + 6502 and 65SC02 instructions. + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + + +<sect1><tt>.POPCPU</tt><label id=".POPCPU"><p> + + Pop the last CPU setting from the stack, and activate it. + + This command will switch back to the CPU that was last pushed onto the CPU + stack using the <tt><ref id=".PUSHCPU" name=".PUSHCPU"></tt> command, and + remove this entry from the stack. + + The assembler will print an error message if the CPU stack is empty when + this command is issued. + + See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".PUSHCPU" + name=".PUSHCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt> + + +<sect1><tt>.POPSEG</tt><label id=".POPSEG"><p> + + Pop the last pushed segment from the stack, and set it. + + This command will switch back to the segment that was last pushed onto the + segment stack using the <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt> + command, and remove this entry from the stack. + + The assembler will print an error message if the segment stack is empty + when this command is issued. + + See: <tt><ref id=".PUSHSEG" name=".PUSHSEG"></tt> + + +<sect1><tt>.PROC</tt><label id=".PROC"><p> + + Start a nested lexical level with the given name and adds a symbol with this + name to the enclosing scope. All new symbols from now on are in the local + lexical level and are accessible from outside only via <ref id="scopesyntax" + name="explicit scope specification">. Symbols defined outside this local + level may be accessed as long as their names are not used for new symbols + inside the level. Symbols names in other lexical levels do not clash, so you + may use the same names for identifiers. The lexical level ends when the + <tt><ref id=".ENDPROC" name=".ENDPROC"></tt> command is read. Lexical levels + may be nested up to a depth of 16 (this is an artificial limit to protect + against errors in the source). + + Note: Macro names are always in the global level and in a separate name + space. There is no special reason for this, it's just that I've never + had any need for local macro definitions. + + Example: + + <tscreen><verb> + .proc Clear ; Define Clear subroutine, start new level + lda #$00 + L1: sta Mem,y ; L1 is local and does not cause a + ; duplicate symbol error if used in other + ; places + dey + bne L1 ; Reference local symbol + rts + .endproc ; Leave lexical level + </verb></tscreen> + + See: <tt/<ref id=".ENDPROC" name=".ENDPROC">/ and <tt/<ref id=".SCOPE" + name=".SCOPE">/ + + +<sect1><tt>.PSC02</tt><label id=".PSC02"><p> + + Enable the 65SC02 instructions set. This instruction set includes all + 6502 instructions. + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02" + name=".PC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + + +<sect1><tt>.PUSHCPU</tt><label id=".PUSHCPU"><p> + + Push the currently active CPU onto a stack. The stack has a size of 8 + entries. + + <tt/.PUSHCPU/ allows together with <tt><ref id=".POPCPU" + name=".POPCPU"></tt> to switch to another CPU and to restore the old CPU + later, without knowledge of the current CPU setting. + + The assembler will print an error message if the CPU stack is already full, + when this command is issued. + + See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".POPCPU" + name=".POPCPU"></tt>, <tt><ref id=".SETCPU" name=".SETCPU"></tt> + + +<sect1><tt>.PUSHSEG</tt><label id=".PUSHSEG"><p> + + Push the currently active segment onto a stack. The entries on the stack + include the name of the segment and the segment type. The stack has a size + of 16 entries. + + <tt/.PUSHSEG/ allows together with <tt><ref id=".POPSEG" name=".POPSEG"></tt> + to switch to another segment and to restore the old segment later, without + even knowing the name and type of the current segment. + + The assembler will print an error message if the segment stack is already + full, when this command is issued. + + See: <tt><ref id=".POPSEG" name=".POPSEG"></tt> + + +<sect1><tt>.RELOC</tt><label id=".RELOC"><p> + + Switch back to relocatable mode. See the <tt><ref id=".ORG" + name=".ORG"></tt> command. + + +<sect1><tt>.REPEAT</tt><label id=".REPEAT"><p> + + Repeat all commands between <tt/.REPEAT/ and <tt><ref id=".ENDREPEAT" + name=".ENDREPEAT"></tt> constant number of times. The command is followed by + a constant expression that tells how many times the commands in the body + should get repeated. Optionally, a comma and an identifier may be specified. + If this identifier is found in the body of the repeat statement, it is + replaced by the current repeat count (starting with zero for the first time + the body is repeated). + + <tt/.REPEAT/ statements may be nested. If you use the same repeat count + identifier for a nested <tt/.REPEAT/ statement, the one from the inner + level will be used, not the one from the outer level. + + Example: + + The following macro will emit a string that is "encrypted" in that all + characters of the string are XORed by the value $55. + + <tscreen><verb> + .macro Crypt Arg + .repeat .strlen(Arg), I + .byte .strat(Arg, I) ^ $55 + .endrep + .endmacro + </verb></tscreen> + + See: <tt><ref id=".ENDREPEAT" name=".ENDREPEAT"></tt> + + +<sect1><tt>.RES</tt><label id=".RES"><p> + + Reserve storage. The command is followed by one or two constant + expressions. The first one is mandatory and defines, how many bytes of + storage should be defined. The second, optional expression must by a + constant byte value that will be used as value of the data. If there + is no fill value given, the linker will use the value defined in the + linker configuration file (default: zero). + + Example: + + <tscreen><verb> + ; Reserve 12 bytes of memory with value $AA + .res 12, $AA + </verb></tscreen> + + +<sect1><tt>.RODATA</tt><label id=".RODATA"><p> + + Switch to the RODATA segment. The name of the RODATA segment is always + "RODATA", so this is a shortcut for + + <tscreen><verb> + .segment "RODATA" + </verb></tscreen> + + The RODATA segment is a segment that is used by the compiler for + readonly data like string constants. + + See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. + + +<sect1><tt>.SCOPE</tt><label id=".SCOPE"><p> + + Start a nested lexical level with the given name. All new symbols from now + on are in the local lexical level and are accessible from outside only via + <ref id="scopesyntax" name="explicit scope specification">. Symbols defined + outside this local level may be accessed as long as their names are not used + for new symbols inside the level. Symbols names in other lexical levels do + not clash, so you may use the same names for identifiers. The lexical level + ends when the <tt><ref id=".ENDSCOPE" name=".ENDSCOPE"></tt> command is + read. Lexical levels may be nested up to a depth of 16 (this is an + artificial limit to protect against errors in the source). + + Note: Macro names are always in the global level and in a separate name + space. There is no special reason for this, it's just that I've never + had any need for local macro definitions. + + Example: + + <tscreen><verb> + .scope Error ; Start new scope named Error + None = 0 ; No error + File = 1 ; File error + Parse = 2 ; Parse error + .endscope ; Close lexical level + + ... + lda #Error::File ; Use symbol from scope Error + </verb></tscreen> + + See: <tt/<ref id=".ENDSCOPE" name=".ENDSCOPE">/ and <tt/<ref id=".PROC" + name=".PROC">/ + + +<sect1><tt>.SEGMENT</tt><label id=".SEGMENT"><p> + + Switch to another segment. Code and data is always emitted into a + segment, that is, a named section of data. The default segment is + "CODE". There may be up to 254 different segments per object file + (and up to 65534 per executable). There are shortcut commands for + the most common segments ("CODE", "DATA" and "BSS"). + + The command is followed by a string containing the segment name (there are + some constraints for the name - as a rule of thumb use only those segment + names that would also be valid identifiers). There may also be an optional + address size separated by a colon. See the section covering <tt/<ref + id="address-sizes" name="address sizes">/ for more information. + + The default address size for a segment depends on the memory model specified + on the command line. The default is "absolute", which means that you don't + have to use an address size modifier in most cases. + + "absolute" means that the is a segment with 16 bit (absolute) addressing. + That is, the segment will reside somewhere in core memory outside the zero + page. "zeropage" (8 bit) means that the segment will be placed in the zero + page and direct (short) addressing is possible for data in this segment. + + Beware: Only labels in a segment with the zeropage attribute are marked + as reachable by short addressing. The `*' (PC counter) operator will + work as in other segments and will create absolute variable values. + + Please note that a segment cannot have two different address sizes. A + segment specified as zeropage cannot be declared as being absolute later. + + Examples: + + <tscreen><verb> + .segment "ROM2" ; Switch to ROM2 segment + .segment "ZP2": zeropage ; New direct segment + .segment "ZP2" ; Ok, will use last attribute + .segment "ZP2": absolute ; Error, redecl mismatch + </verb></tscreen> + + See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE" + name=".CODE"></tt>, <tt><ref id=".DATA" name=".DATA"></tt> and <tt><ref + id=".RODATA" name=".RODATA"></tt> + + +<sect1><tt>.SET</tt><label id=".SET"><p> + + <tt/.SET/ is used to assign a value to a variable. See <ref id="variables" + name="Numeric variables"> for a full description. + + +<sect1><tt>.SETCPU</tt><label id=".SETCPU"><p> + + Switch the CPU instruction set. The command is followed by a string that + specifies the CPU. Possible values are those that can also be supplied to + the <tt><ref id="option--cpu" name="--cpu"></tt> command line option, + namely: 6502, 6502X, 65SC02, 65C02, 65816, sunplus and HuC6280. Please + note that support for the sunplus CPU is not available in the freeware + version, because the instruction set of the sunplus CPU is "proprietary + and confidential". + + See: <tt><ref id=".CPU" name=".CPU"></tt>, + <tt><ref id=".IFP02" name=".IFP02"></tt>, + <tt><ref id=".IFP816" name=".IFP816"></tt>, + <tt><ref id=".IFPC02" name=".IFPC02"></tt>, + <tt><ref id=".IFPSC02" name=".IFPSC02"></tt>, + <tt><ref id=".P02" name=".P02"></tt>, + <tt><ref id=".P816" name=".P816"></tt>, + <tt><ref id=".PC02" name=".PC02"></tt>, + <tt><ref id=".PSC02" name=".PSC02"></tt> + + +<sect1><tt>.SMART</tt><label id=".SMART"><p> + + Switch on or off smart mode. The command must be followed by a '+' or '-' + character to switch the option on or off respectively. The default is off + (that is, the assembler doesn't try to be smart), but this default may be + changed by the -s switch on the command line. + + In smart mode the assembler will do the following: + + <itemize> + <item>Track usage of the <tt/REP/ and <tt/SEP/ instructions in 65816 mode + and update the operand sizes accordingly. If the operand of such an + instruction cannot be evaluated by the assembler (for example, because + the operand is an imported symbol), a warning is issued. Beware: Since + the assembler cannot trace the execution flow this may lead to false + results in some cases. If in doubt, use the <tt/.Inn/ and <tt/.Ann/ + instructions to tell the assembler about the current settings. + <item>In 65816 mode, replace a <tt/RTS/ instruction by <tt/RTL/ if it is + used within a procedure declared as <tt/far/, or if the procedure has + no explicit address specification, but it is <tt/far/ because of the + memory model used. + </itemize> + + Example: + + <tscreen><verb> + .smart ; Be smart + .smart - ; Stop being smart + </verb></tscreen> + + See: <tt><ref id=".A16" name=".A16"></tt>, + <tt><ref id=".A8" name=".A8"></tt>, + <tt><ref id=".I16" name=".I16"></tt>, + <tt><ref id=".I8" name=".I8"></tt> + + +<sect1><tt>.STRUCT</tt><label id=".STRUCT"><p> + + Starts a struct definition. Structs are covered in a separate section named + <ref id="structs" name=""Structs and unions"">. + + See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>, + <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>, + <tt><ref id=".UNION" name=".UNION"></tt> + + +<sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p> + + Enable the SunPlus instructions set. This command will not work in the + freeware version of the assembler, because the instruction set is + "proprietary and confidential". + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, and + <tt><ref id=".P816" name=".P816"></tt> + + +<sect1><tt>.TAG</tt><label id=".TAG"><p> + + Allocate space for a struct or union. + + Example: + + <tscreen><verb> + .struct Point + xcoord .word + ycoord .word + .endstruct + + .bss + .tag Point ; Allocate 4 bytes + </verb></tscreen> + + +<sect1><tt>.UNDEF, .UNDEFINE</tt><label id=".UNDEFINE"><p> + + Delete a define style macro definition. The command is followed by an + identifier which specifies the name of the macro to delete. Macro + replacement is switched of when reading the token following the command + (otherwise the macro name would be replaced by its replacement list). + + See also the <tt><ref id=".DEFINE" name=".DEFINE"></tt> command and + section <ref id="macros" name="Macros">. + + +<sect1><tt>.UNION</tt><label id=".UNION"><p> + + Starts a union definition. Unions are covered in a separate section named + <ref id="structs" name=""Structs and unions"">. + + See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>, + <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>, + <tt><ref id=".STRUCT" name=".STRUCT"></tt> + + +<sect1><tt>.WARNING</tt><label id=".WARNING"><p> + + Force an assembly warning. The assembler will output a warning message + preceded by "User warning". This warning will always be output, even if + other warnings are disabled with the <tt><ref id="option-W" name="-W0"></tt> + command line option. + + This command may be used to output possible problems when assembling + the source file. + + Example: + + <tscreen><verb> + .macro jne target + .local L1 + .ifndef target + .warning "Forward jump in jne, cannot optimize!" + beq L1 + jmp target + L1: + .else + ... + .endif + .endmacro + </verb></tscreen> + + See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, + <tt><ref id=".FATAL" name=".FATAL"></tt>, + <tt><ref id=".OUT" name=".OUT"></tt> + + +<sect1><tt>.WORD</tt><label id=".WORD"><p> + + Define word sized data. Must be followed by a sequence of (word ranged, + but not necessarily constant) expressions. + + Example: + + <tscreen><verb> + .word $0D00, $AF13, _Clear + </verb></tscreen> + + +<sect1><tt>.ZEROPAGE</tt><label id=".ZEROPAGE"><p> + + Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment. + The name of the ZEROPAGE segment is always "ZEROPAGE", so this is a + shortcut for + + <tscreen><verb> + .segment "ZEROPAGE", zeropage + </verb></tscreen> + + Because of the "zeropage" attribute, labels declared in this segment are + addressed using direct addressing mode if possible. You <em/must/ instruct + the linker to place this segment somewhere in the address range 0..$FF + otherwise you will get errors. + + See: <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> + + + +<sect>Macros<label id="macros"><p> + + +<sect1>Introduction<p> + +Macros may be thought of as "parametrized super instructions". Macros are +sequences of tokens that have a name. If that name is used in the source +file, the macro is "expanded", that is, it is replaced by the tokens that +were specified when the macro was defined. + + +<sect1>Macros without parameters<p> + +In its simplest form, a macro does not have parameters. Here's an +example: + +<tscreen><verb> + .macro asr ; Arithmetic shift right + cmp #$80 ; Put bit 7 into carry + ror ; Rotate right with carry + .endmacro +</verb></tscreen> + +The macro above consists of two real instructions, that are inserted into +the code, whenever the macro is expanded. Macro expansion is simply done +by using the name, like this: + +<tscreen><verb> + lda $2010 + asr + sta $2010 +</verb></tscreen> + + +<sect1>Parametrized macros<p> + +When using macro parameters, macros can be even more useful: + +<tscreen><verb> + .macro inc16 addr + clc + lda addr + adc #$01 + sta addr + lda addr+1 + adc #$00 + sta addr+1 + .endmacro +</verb></tscreen> + +When calling the macro, you may give a parameter, and each occurrence of +the name "addr" in the macro definition will be replaced by the given +parameter. So + +<tscreen><verb> + inc16 $1000 +</verb></tscreen> + +will be expanded to + +<tscreen><verb> + clc + lda $1000 + adc #$01 + sta $1000 + lda $1000+1 + adc #$00 + sta $1000+1 +</verb></tscreen> + +A macro may have more than one parameter, in this case, the parameters +are separated by commas. You are free to give less parameters than the +macro actually takes in the definition. You may also leave intermediate +parameters empty. Empty parameters are replaced by empty space (that is, +they are removed when the macro is expanded). If you have a look at our +macro definition above, you will see, that replacing the "addr" parameter +by nothing will lead to wrong code in most lines. To help you, writing +macros with a variable parameter list, there are some control commands: + +<tt><ref id=".IFBLANK" name=".IFBLANK"></tt> tests the rest of the line and +returns true, if there are any tokens on the remainder of the line. Since +empty parameters are replaced by nothing, this may be used to test if a given +parameter is empty. <tt><ref id=".IFNBLANK" name=".IFNBLANK"></tt> tests the +opposite. + +Look at this example: + +<tscreen><verb> + .macro ldaxy a, x, y + .ifnblank a + lda #a + .endif + .ifnblank x + ldx #x + .endif + .ifnblank y + ldy #y + .endif + .endmacro +</verb></tscreen> + +This macro may be called as follows: + +<tscreen><verb> + ldaxy 1, 2, 3 ; Load all three registers + + ldaxy 1, , 3 ; Load only a and y + + ldaxy , , 3 ; Load y only +</verb></tscreen> + +There's another helper command for determining, which macro parameters are +valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt> This command is +replaced by the parameter count given, <em/including/ intermediate empty macro +parameters: + +<tscreen><verb> + ldaxy 1 ; .PARAMCOUNT = 1 + ldaxy 1,,3 ; .PARAMCOUNT = 3 + ldaxy 1,2 ; .PARAMCOUNT = 2 + ldaxy 1, ; .PARAMCOUNT = 2 + ldaxy 1,2,3 ; .PARAMCOUNT = 3 +</verb></tscreen> + +Macro parameters may optionally be enclosed into curly braces. This allows the +inclusion of tokens that would otherwise terminate the parameter (the comma in +case of a macro parameter). + +<tscreen><verb> + .macro foo arg1, arg2 + ... + .endmacro + + foo ($00,x) ; Two parameters passed + foo {($00,x)} ; One parameter passed +</verb></tscreen> + +In the first case, the macro is called with two parameters: '<tt/($00/' +and 'x)'. The comma is not passed to the macro, since it is part of the +calling sequence, not the parameters. + +In the second case, '($00,x)' is passed to the macro, this time +including the comma. + + +<sect1>Detecting parameter types<p> + +Sometimes it is nice to write a macro that acts differently depending on the +type of the argument supplied. An example would be a macro that loads a 16 bit +value from either an immediate operand, or from memory. The <tt/<ref +id=".MATCH" name=".MATCH">/ and <tt/<ref id=".XMATCH" name=".XMATCH">/ +functions will allow you to do exactly this: + +<tscreen><verb> + .macro ldax arg + .if (.match (.left (1, {arg}), #)) + ; immediate mode + lda #<(.right (.tcount ({arg})-1, {arg})) + ldx #>(.right (.tcount ({arg})-1, {arg})) + .else + ; assume absolute or zero page + lda arg + ldx 1+(arg) + .endif + .endmacro +</verb></tscreen> + +Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to +check if its argument begins with a hash mark. If so, two immediate loads are +emitted, Otherwise a load from an absolute zero page memory location is +assumed. Please note how the curly braces are used to enclose parameters to +pseudo functions handling token lists. This is necessary, because the token +lists may include commas or parens, which would be treated by the assembler +as end-of-list. + +The macro can be used as + +<tscreen><verb> + foo: .word $5678 + ... + ldax #$1234 ; X=$12, A=$34 + ... + ldax foo ; X=$56, A=$78 +</verb></tscreen> + + +<sect1>Recursive macros<p> + +Macros may be used recursively: + +<tscreen><verb> + .macro push r1, r2, r3 + lda r1 + pha + .if .paramcount > 1 + push r2, r3 + .endif + .endmacro +</verb></tscreen> + +There's also a special macro to help writing recursive macros: <tt><ref +id=".EXITMACRO" name=".EXITMACRO"></tt> This command will stop macro expansion +immediately: + +<tscreen><verb> + .macro push r1, r2, r3, r4, r5, r6, r7 + .ifblank r1 + ; First parameter is empty + .exitmacro + .else + lda r1 + pha + .endif + push r2, r3, r4, r5, r6, r7 + .endmacro +</verb></tscreen> + +When expanding this macro, the expansion will push all given parameters +until an empty one is encountered. The macro may be called like this: + +<tscreen><verb> + push $20, $21, $32 ; Push 3 ZP locations + push $21 ; Push one ZP location +</verb></tscreen> + + +<sect1>Local symbols inside macros<p> + +Now, with recursive macros, <tt><ref id=".IFBLANK" name=".IFBLANK"></tt> and +<tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>, what else do you need? +Have a look at the inc16 macro above. Here is it again: + +<tscreen><verb> + .macro inc16 addr + clc + lda addr + adc #$01 + sta addr + lda addr+1 + adc #$00 + sta addr+1 + .endmacro +</verb></tscreen> + +If you have a closer look at the code, you will notice, that it could be +written more efficiently, like this: + +<tscreen><verb> + .macro inc16 addr + inc addr + bne Skip + inc addr+1 + Skip: + .endmacro +</verb></tscreen> + +But imagine what happens, if you use this macro twice? Since the label "Skip" +has the same name both times, you get a "duplicate symbol" error. Without a +way to circumvent this problem, macros are not as useful, as they could be. +One possible solution is the command <tt><ref id=".LOCAL" name=".LOCAL"></tt>. +It declares one or more symbols as local to the macro expansion. The names of +local variables are replaced by a unique name in each separate macro +expansion. So we can solve the problem above by using <tt/.LOCAL/: + +<tscreen><verb> + .macro inc16 addr + .local Skip ; Make Skip a local symbol + inc addr + bne Skip + inc addr+1 + Skip: ; Not visible outside + .endmacro +</verb></tscreen> + +Another solution is of course to start a new lexical block inside the macro +that hides any labels: + +<tscreen><verb> + .macro inc16 addr + .proc + inc addr + bne Skip + inc addr+1 + Skip: + .endproc + .endmacro +</verb></tscreen> + + +<sect1>C style macros<p> + +Starting with version 2.5 of the assembler, there is a second macro type +available: C style macros using the <tt/.DEFINE/ directive. These macros are +similar to the classic macro type described above, but behaviour is sometimes +different: + +<itemize> + +<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> may not + span more than a line. You may use line continuation (see <tt><ref + id=".LINECONT" name=".LINECONT"></tt>) to spread the definition over + more than one line for increased readability, but the macro itself + may not contain an end-of-line token. + +<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> share + the name space with classic macros, but they are detected and replaced + at the scanner level. While classic macros may be used in every place, + where a mnemonic or other directive is allowed, <tt><ref id=".DEFINE" + name=".DEFINE"></tt> style macros are allowed anywhere in a line. So + they are more versatile in some situations. + +<item> <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may take + parameters. While classic macros may have empty parameters, this is + not true for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros. + For this macro type, the number of actual parameters must match + exactly the number of formal parameters. + + To make this possible, formal parameters are enclosed in braces when + defining the macro. If there are no parameters, the empty braces may + be omitted. + +<item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not + contain end-of-line tokens, there are things that cannot be done. They + may not contain several processor instructions for example. So, while + some things may be done with both macro types, each type has special + usages. The types complement each other. + +</itemize> + +Let's look at a few examples to make the advantages and disadvantages +clear. + +To emulate assemblers that use "<tt/EQU/" instead of "<tt/=/" you may use the +following <tt/.DEFINE/: + +<tscreen><verb> + .define EQU = + + foo EQU $1234 ; This is accepted now +</verb></tscreen> + +You may use the directive to define string constants used elsewhere: + +<tscreen><verb> + ; Define the version number + .define VERSION "12.3a" + + ; ... and use it + .asciiz VERSION +</verb></tscreen> + +Macros with parameters may also be useful: + +<tscreen><verb> + .define DEBUG(message) .out message + + DEBUG "Assembling include file #3" +</verb></tscreen> + +Note that, while formal parameters have to be placed in braces, this is +not true for the actual parameters. Beware: Since the assembler cannot +detect the end of one parameter, only the first token is used. If you +don't like that, use classic macros instead: + +<tscreen><verb> + .macro DEBUG message + .out message + .endmacro +</verb></tscreen> + +(This is an example where a problem can be solved with both macro types). + + +<sect1>Characters in macros<p> + +When using the <ref id="option-t" name="-t"> option, characters are translated +into the target character set of the specific machine. However, this happens +as late as possible. This means that strings are translated if they are part +of a <tt><ref id=".BYTE" name=".BYTE"></tt> or <tt><ref id=".ASCIIZ" +name=".ASCIIZ"></tt> command. Characters are translated as soon as they are +used as part of an expression. + +This behaviour is very intuitive outside of macros but may be confusing when +doing more complex macros. If you compare characters against numeric values, +be sure to take the translation into account. + + +<sect1>Deleting macros<p> + +Macros can be deleted. This will not work if the macro that should be deleted +is currently expanded as in the following non working example: + +<tscreen><verb> + .macro notworking + .delmacro notworking + .endmacro + + notworking ; Will not work +</verb></tscreen> + +The commands to delete classic and define style macros differ. Classic macros +can be deleted by use of <tt><ref id=".DELMACRO" name=".DELMACRO"></tt>, while +for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros, <tt><ref +id=".UNDEFINE" name=".UNDEFINE"></tt> must be used. Example: + +<tscreen><verb> + .define value 1 + .macro mac + .byte 2 + .endmacro + + .byte value ; Emit one byte with value 1 + mac ; Emit another byte with value 2 + + .undefine value + .delmacro mac + + .byte value ; Error: Unknown identifier + mac ; Error: Missing ":" +</verb></tscreen> + +A separate command for <tt>.DEFINE</tt> style macros was necessary, because +the name of such a macro is replaced by its replacement list on a very low +level. To get the actual name, macro replacement has to be switched off when +reading the argument to <tt>.UNDEFINE</tt>. This does also mean that the +argument to <tt>.UNDEFINE</tt> is not allowed to come from another +<tt>.DEFINE</tt>. All this is not necessary for classic macros, so having two +different commands increases flexibility. + + +<sect>Macro packages<label id="macropackages"><p> + +Using the <tt><ref id=".MACPACK" name=".MACPACK"></tt> directive, predefined +macro packages may be included with just one command. Available macro packages +are: + + +<sect1><tt>.MACPACK generic</tt><p> + +This macro package defines macros that are useful in almost any program. +Currently defined macros are: + +<tscreen><verb> + .macro add Arg + clc + adc Arg + .endmacro + + .macro sub Arg + sec + sbc Arg + .endmacro + + .macro bge Arg + bcs Arg + .endmacro + + .macro blt Arg + bcc Arg + .endmacro + + .macro bgt Arg + .local L + beq L + bcs Arg + L: + .endmacro + + .macro ble Arg + beq Arg + bcc Arg + .endmacro +</verb></tscreen> + + +<sect1><tt>.MACPACK longbranch</tt><p> + +This macro package defines long conditional jumps. They are named like the +short counterpart but with the 'b' replaced by a 'j'. Here is a sample +definition for the "<tt/jeq/" macro, the other macros are built using the same +scheme: + +<tscreen><verb> + .macro jeq Target + .if .def(Target) .and ((*+2)-(Target) <= 127) + beq Target + .else + bne *+5 + jmp Target + .endif + .endmacro +</verb></tscreen> + +All macros expand to a short branch, if the label is already defined (back +jump) and is reachable with a short jump. Otherwise the macro expands to a +conditional branch with the branch condition inverted, followed by an absolute +jump to the actual branch target. + +The package defines the following macros: + +<tscreen><verb> + jeq, jne, jmi, jpl, jcs, jcc, jvs, jvc +</verb></tscreen> + + + +<sect1><tt>.MACPACK atari</tt><p> + +The atari macro package will define a macro named <tt/scrcode/. It takes a +string as argument and places this string into memory translated into screen +codes. + + +<sect1><tt>.MACPACK cbm</tt><p> + +The cbm macro package will define a macro named <tt/scrcode/. It takes a +string as argument and places this string into memory translated into screen +codes. + + +<sect1><tt>.MACPACK cpu</tt><p> + +This macro package does not define any macros but constants used to examine +the value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable. For +each supported CPU a constant similar to + +<tscreen><verb> + CPU_6502 + CPU_65SC02 + CPU_65C02 + CPU_65816 + CPU_SUNPLUS + CPU_SWEET16 + CPU_HUC6280 +</verb></tscreen> + +is defined. These constants may be used to determine the exact type of the +currently enabled CPU. In addition to that, for each CPU instruction set, +another constant is defined: + +<tscreen><verb> + CPU_ISET_6502 + CPU_ISET_65SC02 + CPU_ISET_65C02 + CPU_ISET_65816 + CPU_ISET_SUNPLUS + CPU_ISET_SWEET16 + CPU_ISET_HUC6280 +</verb></tscreen> + +The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may +be checked with <tt/<ref id="operators" name=".BITAND">/ to determine if the +currently enabled CPU supports a specific instruction set. For example the +65C02 supports all instructions of the 65SC02 CPU, so it has the +<tt/CPU_ISET_65SC02/ bit set in addition to its native <tt/CPU_ISET_65C02/ +bit. Using + +<tscreen><verb> + .if (.cpu .bitand CPU_ISET_65SC02) + lda (sp) + .else + ldy #$00 + lda (sp),y + .endif +</verb></tscreen> + +it is possible to determine if the + +<tscreen><verb> + lda (sp) +</verb></tscreen> + +instruction is supported, which is the case for the 65SC02, 65C02 and 65816 +CPUs (the latter two are upwards compatible to the 65SC02). + + + +<sect>Predefined constants<label id="predefined-constants"><p> + +For better orthogonality, the assembler defines similar symbols as the +compiler, depending on the target system selected: + +<itemize> +<item><tt/__APPLE2__/ - Target system is <tt/apple2/ +<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/ +<item><tt/__ATARI__/ - Target system is <tt/atari/ +<item><tt/__ATMOS__/ - Target system is <tt/atmos/ +<item><tt/__BBC__/ - Target system is <tt/bbc/ +<item><tt/__C128__/ - Target system is <tt/c128/ +<item><tt/__C16__/ - Target system is <tt/c16/ +<item><tt/__C64__/ - Target system is <tt/c64/ +<item><tt/__CBM__/ - Target is a Commodore system +<item><tt/__CBM510__/ - Target system is <tt/cbm510/ +<item><tt/__CBM610__/ - Target system is <tt/cbm610/ +<item><tt/__GEOS__/ - Target system is <tt/geos/ +<item><tt/__LUNIX__/ - Target system is <tt/lunix/ +<item><tt/__NES__/ - Target system is <tt/nes/ +<item><tt/__PET__/ - Target system is <tt/pet/ +<item><tt/__PLUS4__/ - Target system is <tt/plus4/ +<item><tt/__SUPERVISION__/ - Target system is <tt/supervision/ +<item><tt/__VIC20__/ - Target system is <tt/vic20/ +</itemize> + + +<sect>Structs and unions<label id="structs"><p> + +<sect1>Structs and unions Overview<p> + +Structs and unions are special forms of <ref id="scopes" name="scopes">. They +are to some degree comparable to their C counterparts. Both have a list of +members. Each member allocates storage and may optionally have a name, which, +in case of a struct, is the offset from the beginning and, in case of a union, +is always zero. + + +<sect1>Declaration<p> + +Here is an example for a very simple struct with two members and a total size +of 4 bytes: + +<tscreen><verb> + .struct Point + xcoord .word + ycoord .word + .endstruct +</verb></tscreen> + +A union shares the total space between all its members, its size is the same +as that of the largest member. The offset of all members relative to the union +is zero. + +<tscreen><verb> + .union Entry + index .word + ptr .addr + .endunion +</verb></tscreen> + +A struct or union must not necessarily have a name. If it is anonymous, no +local scope is opened, the identifiers used to name the members are placed +into the current scope instead. + +A struct may contain unnamed members and definitions of local structs. The +storage allocators may contain a multiplier, as in the example below: + +<tscreen><verb> + .struct Circle + .struct Point + .word 2 ; Allocate two words + .endstruct + Radius .word + .endstruct +</verb></tscreen> + + +<sect1>The <tt/.TAG/ keyword<p> + +Using the <ref id=".TAG" name=".TAG"> keyword, it is possible to reserve space +for an already defined struct or unions within another struct: + +<tscreen><verb> + .struct Point + xcoord .word + ycoord .word + .endstruct + + .struct Circle + Origin .tag Point + Radius .byte + .endstruct +</verb></tscreen> + +Space for a struct or union may be allocated using the <ref id=".TAG" +name=".TAG"> directive. + +<tscreen><verb> + C: .tag Circle +</verb></tscreen> + +Currently, members are just offsets from the start of the struct or union. To +access a field of a struct, the member offset has to be added to the address +of the struct itself: + +<tscreen><verb> + lda C+Circle::Radius ; Load circle radius into A +</verb></tscreen> + +This may change in a future version of the assembler. + + +<sect1>Limitations<p> + +Structs and unions are currently implemented as nested symbol tables (in fact, +they were a by-product of the improved scoping rules). Currently, the +assembler has no idea of types. This means that the <ref id=".TAG" +name=".TAG"> keyword will only allocate space. You won't be able to initialize +variables declared with <ref id=".TAG" name=".TAG">, and adding an embedded +structure to another structure with <ref id=".TAG" name=".TAG"> will not make +this structure accessible by using the '::' operator. + + + +<sect>Module constructors/destructors<label id="condes"><p> + +<em>Note:</em> This section applies mostly to C programs, so the explanation +below uses examples from the C libraries. However, the feature may also be +useful for assembler programs. + + +<sect1>Module constructors/destructors Overview<p> + +Using the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref +id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" +name=".INTERRUPTOR"></tt> keywords it is possible to export functions in a +special way. The linker is able to generate tables with all functions of a +specific type. Such a table will <em>only</em> include symbols from object +files that are linked into a specific executable. This may be used to add +initialization and cleanup code for library modules, or a table of interrupt +handler functions. + +The C heap functions are an example where module initialization code is used. +All heap functions (<tt>malloc</tt>, <tt>free</tt>, ...) work with a few +variables that contain the start and the end of the heap, pointers to the free +list and so on. Since the end of the heap depends on the size and start of the +stack, it must be initialized at runtime. However, initializing these +variables for programs that do not use the heap are a waste of time and +memory. + +So the central module defines a function that contains initialization code and +exports this function using the <tt/.CONSTRUCTOR/ statement. If (and only if) +this module is added to an executable by the linker, the initialization +function will be placed into the table of constructors by the linker. The C +startup code will call all constructors before <tt/main/ and all destructors +after <tt/main/, so without any further work, the heap initialization code is +called once the module is linked in. + +While it would be possible to add explicit calls to initialization functions +in the startup code, the new approach has several advantages: + +<enum> +<item> +If a module is not included, the initialization code is not linked in and not +called. So you don't pay for things you don't need. + +<item> +Adding another library that needs initialization does not mean that the +startup code has to be changed. Before we had module constructors and +destructors, the startup code for all systems had to be adjusted to call the +new initialization code. + +<item> +The feature saves memory: Each additional initialization function needs just +two bytes in the table (a pointer to the function). + +</enum> + + +<sect1>Calling order<p> + +The symbols are sorted in increasing priority order by the linker when using +one of the builtin linker configurations, so the functions with lower +priorities come first and are followed by those with higher priorities. The C +library runtime subroutine that walks over the function tables calls the +functions starting from the top of the table - which means that functions with +a high priority are called first. + +So when using the C runtime, functions are called with high priority functions +first, followed by low priority functions. + + +<sect1>Pitfalls<p> + +When using these special symbols, please take care of the following: + +<itemize> + +<item> +The linker will only generate function tables, it will not generate code to +call these functions. If you're using the feature in some other than the +existing C environments, you have to write code to call all functions in a +linker generated table yourself. See the <tt/condes/ and <tt/callirq/ modules +in the C runtime for an example on how to do this. + +<item> +The linker will only add addresses of functions that are in modules linked to +the executable. This means that you have to be careful where to place the +condes functions. If initialization or an irq handler is needed for a group of +functions, be sure to place the function into a module that is linked in +regardless of which function is called by the user. + +<item> +The linker will generate the tables only when requested to do so by the +<tt/FEATURE CONDES/ statement in the linker config file. Each table has to +be requested separately. + +<item> +Constructors and destructors may have priorities. These priorities determine +the order of the functions in the table. If your initialization or cleanup code +does depend on other initialization or cleanup code, you have to choose the +priority for the functions accordingly. + +<item> +Besides the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref +id=".DESTRUCTOR" name=".DESTRUCTOR"></tt> and <tt><ref id=".INTERRUPTOR" +name=".INTERRUPTOR"></tt> statements, there is also a more generic command: +<tt><ref id=".CONDES" name=".CONDES"></tt>. This allows to specify an +additional type. Predefined types are 0 (constructor), 1 (destructor) and 2 +(interruptor). The linker generates a separate table for each type on request. + +</itemize> + + +<sect>Porting sources from other assemblers<p> + +Sometimes it is necessary to port code written for older assemblers to ca65. +In some cases, this can be done without any changes to the source code by +using the emulation features of ca65 (see <tt><ref id=".FEATURE" +name=".FEATURE"></tt>). In other cases, it is necessary to make changes to the +source code. + +Probably the biggest difference is the handling of the <tt><ref id=".ORG" +name=".ORG"></tt> directive. ca65 generates relocatable code, and placement is +done by the linker. Most other assemblers generate absolute code, placement is +done within the assembler and there is no external linker. + +In general it is not a good idea to write new code using the emulation +features of the assembler, but there may be situations where even this rule is +not valid. + +<sect1>TASS<p> + +You need to use some of the ca65 emulation features to simulate the behaviour +of such simple assemblers. + +<enum> +<item>Prepare your sourcecode like this: + +<tscreen><verb> + ; if you want TASS style labels without colons + .feature labels_without_colons + + ; if you want TASS style character constants + ; ("a" instead of the default 'a') + .feature loose_char_term + + .word *+2 ; the cbm load address + + [yourcode here] +</verb></tscreen> + +notice that the two emulation features are mostly useful for porting +sources originally written in/for TASS, they are not needed for the +actual "simple assembler operation" and are not recommended if you are +writing new code from scratch. + +<item>Replace all program counter assignments (which are not possible in ca65 +by default, and the respective emulation feature works different from what +you'd expect) by another way to skip to memory locations, for example the +<tt><ref id=".RES" name=".RES"></tt> directive. + +<tscreen><verb> + ; *=$2000 + .res $2000-* ; reserve memory up to $2000 +</verb></tscreen> + +Please note that other than the original TASS, ca65 can never move the program +counter backwards - think of it as if you are assembling to disk with TASS. + +<item>Conditional assembly (<tt/.ifeq//<tt/.endif//<tt/.goto/ etc.) must be +rewritten to match ca65 syntax. Most importantly notice that due to the lack +of <tt/.goto/, everything involving loops must be replaced by +<tt><ref id=".REPEAT" name=".REPEAT"></tt>. + +<item>To assemble code to a different address than it is executed at, use the +<tt><ref id=".ORG" name=".ORG"></tt> directive instead of +<tt/.offs/-constructs. + +<tscreen><verb> + .org $1800 + + [floppy code here] + + .reloc ; back to normal +</verb></tscreen> + +<item>Then assemble like this: + +<tscreen><verb> + cl65 --start-addr 0x0ffe -t none myprog.s -o myprog.prg +</verb></tscreen> + +Note that you need to use the actual start address minus two, since two bytes +are used for the cbm load address. + +</enum> + + +<sect>Bugs/Feedback<p> + +If you have problems using the assembler, if you find any bugs, or if +you're doing something interesting with the assembler, I would be glad to +hear from you. Feel free to contact me by email +(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ca65 (and all cc65 binutils) are (C) Copyright 1998-2003 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + + + diff --git a/doc/ca65html.sgml b/doc/ca65html.sgml new file mode 100644 index 000000000..8b26be44c --- /dev/null +++ b/doc/ca65html.sgml @@ -0,0 +1,289 @@ +<!doctype linuxdoc system> + +<article> +<title>ca65html Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2007-10-2 + +<abstract> +ca65html is an assembly-source-to-HTML converter. It is very useful if you +want to publish your assembler sources in the web. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +ca65html converts assembly source files written for use with the <tt/<url +url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone +tool written in PERL; and as such, it does not understand the structure of +assembler sources in the same depth as ca65 does, so it may fail in very rare +cases. In all other cases, it generates very nice output. + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The HTML converter accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: ca65html [options] file ... +Options: + --bgcolor c Use background color c instead of #FFFFFF + --colorize Add color highlights to the output + --commentcolor c Use color c for comments instead of #B22222 + --crefs Generate references to the C source file(s) + --ctrlcolor c Use color c for directives instead of #228B22 + --cvttabs Convert tabs to spaces in the output + --help This text + --htmldir dir Specify directory for HTML files + --indexcols n Use n columns on index page (default 6) + --indexname file Use file for the index file instead of index.html + --indexpage Create an index page + --indextitle title Use title as the index title instead of Index + --keywordcolor c Use color c for keywords instead of #A020F0 + --linelabels Generate a linexxx HTML label for each line + --linenumbers Add line numbers to the output + --linkstyle style Use the given link style + --replaceext Replace source extension instead of appending .html + --textcolor c Use text color c instead of #000000 + --verbose Be more verbose +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <tag><tt>--bgcolor c</tt></tag> + + Set the background color. The argument c must be a valid HTML color, usually + given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are the + respective red, green, and blue parts as two-digit hex values. The default is + <tt/#FFFFFF/ (white). That color is used in the <tt/<body>/ of the + generated HTML output. + + + <tag><tt>--colorize</tt></tag> + + Colorize the output. The converter outputs processor instructions, assembler + control commands, and comments in different colors. + + + <tag><tt>--commentcolor c</tt></tag> + + Set the color used for comments. The argument c must be a valid HTML color, + usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are + the respective red, green, and blue parts as two-digit hex values. The + default is <tt/#B22222/ (red). + + Note that this option has no effect if <tt/--colorize/ is not also given. + + + <tag><tt>--crefs</tt></tag> + + Generate references to the C file, when a <tt/.dbg/ command is found with a + file name. The converter assumes that the C source was also converted into + HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and + lives in the same directory as the assembler file. If the <tt/.dbg/ + directive specifies a line, a link to the correct line in the C file is + generated, using a label in the form <tt/linexxx/, as it is created by + <tt/c2html/ by use of the <tt/-n/ option. + + + <tag><tt>--commentcolor c</tt></tag> + + Set the color used for assembler control commands. The argument c must be a + valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/, + where r, g, and b are the respective red, green, and blue parts as two-digit + hex values. The default is <tt/#228B22/ (green). + + Note that this option has no effect if <tt/--colorize/ is not also given. + + + <tag><tt>--cvttabs</tt></tag> + + Convert tabs in the input into spaces in the output, assuming the standard + tab width of 8. This is useful if the <tt/--linenumbers/ option is used to + retain the indentation. + + + <tag><tt>--help</tt></tag> + + Print the command line option summary shown above. + + + <tag><tt>--htmldir dir</tt></tag> + + Specify an output directory for the generated HTML files. + + + <tag><tt>--indexcols n</tt></tag> + + Use n columns on the index page. This option has no effect if used without + <tt/--indexpage/. + + + <tag><tt>--indexname name</tt></tag> + + Use another index file name instead of <tt/index.html/. This option has no + effect if used without <tt/--indexpage/. + + + <tag><tt>--indexpage</tt></tag> + + Causes the converter to generate an index page listing file names, and all + exports found in the converted files. + + + <tag><tt>--indextitle title</tt></tag> + + Use "title" as the title of the index page. This option has no effect if + used without <tt/--indexpage/. + + + <tag><tt>--keywordcolor c</tt></tag> + + Set the color used for processor instructions. The argument c must be a + valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/, + where r, g, and b are the respective red, green, and blue parts as two-digit + hex values. The default is <tt/#A020F0/ (purple). + + Note that this option has no effect if <tt/--colorize/ is not also given. + + <tag><tt>--linelabels</tt></tag> + + Generate a label for each line using the name <tt/linexxx/ where xxx is the + number of the line. + + Note: The converter will not make use of this label. Use this option if you + have other HTML pages referencing the converted assembler file. + + + <tag><tt>--linenumbers</tt></tag> + + Generate line numbers on the left side of the output. + + + <tag><tt>--linkstyle n</tt></tag> + + Influences the style used when generating links for imports. If n is zero + (the default), the converter creates a link to the actual symbol if it is + defined somewhere in the input files. If not, it creates a link to the + <tt/.import/ statement. If n is one, the converter will always generate a + HTML link to the <tt/.import/ statement. + + + <tag><tt>--replaceext</tt></tag> + + Replace the file extension of the input file instead of appending <tt/.html/ + when generating the output file name. + + + <tag><tt>--textcolor c</tt></tag> + + Set the color for normal text. The argument c must be a valid HTML color, + usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are + the respective red, green, and blue parts as two-digit hex values. The + default is <tt/#000000/ (black). This color is used in the <tt/<body>/ + of the generated HTML output. + + + <tag><tt>--verbose</tt></tag> + + Increase the converter verbosity. Without this option, ca65html is quiet + when working. If you have a slow machine and lots of files to convert, you + might like a little bit more progress information. + +</descrip> +<p> + + +<sect>Peculiarities<p> + +<sect1>Cross links<p> + +Since ca65html is able to generate links between modules, the best way to use +it is to supply all modules to it in one run, instead of running each file +separately through it. + + +<sect1>Include files<p> + +For now, ca65html will not read files included with <tt/.include/. Specifying +the include files as normal input files on the command line works in many +cases. + + +<sect1>Conversion errors<p> + +Since ca65html does not really parse the input, but does most of its work +applying text patterns, it doesn't know anything about scoping and advanced +features of the assembler. This means that it might miss a label. And, it +might choose the wrong color for an item, in rare cases. Because it's just a +tool for displaying sources in a nice form, I think that's OK. Anyway, if you +find a conversion problem, you can send me a short piece of example input code. +If possible, I will fix it. + + +<sect1>Colorization<p> + +While having colors in the output looks really nice, it has one drawback: + +<enum> + +<item>Because lots of <tt/<span>/ tags are created in the output, +the size of the output file literally will explode. It seems to be the price +that you have to pay for color. + +</enum> + + +<sect>Bugs/Feedback<p> + +If you have problems using the converter, if you find any bugs, or if you're +doing something interesting with the assembler, I would be glad to hear from +you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the +following conditions apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + + + diff --git a/doc/cbm510.sgml b/doc/cbm510.sgml new file mode 100644 index 000000000..0dc842bc1 --- /dev/null +++ b/doc/cbm510.sgml @@ -0,0 +1,301 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 510 (aka P500) specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2006-05-22 + +<abstract> +An overview over the Commodore 510 runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the CBM 510 runtime system as it comes with +the cc65 C compiler. It describes the memory layout, CBM 510 specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that CBM 510 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + +In addition to the Commodore 510 (named P128 in the U.S.), no other +machines are supported by this cc65 target. + + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Commodore +510 target is a machine language program with a one line BASIC stub, which +transfers control to the machine language running in bank 0. This means that a +program can be loaded as BASIC program and started with RUN. It is of course +possible to change this behaviour by using a modified startup file and linker +config. + + + +<sect>Memory layout<p> + +cc65 generated programs for the Commodore 510 run in bank 0, the memory bank +reserved for BASIC programs. Since there are no ROMs in this memory bank, +kernal subroutines are either emulated or called by bank switching, which has +the disadvantage of being slow compared to a direct call. + +The default memory configuration for the CBM 510 allocates all memory between +$0002 and $FFF0 in bank 0 for the compiled program. Some space +in low memory is lost, because a separate hardware stack is set up in page 1, +and the kernal replacement functions need some more memory locations. A few +more pages are lost in high memory, because the runtime sets up a copy of the +character ROM, a text screen and a CBM compatible jump table at $FF81. +The main startup code is located at $0400, so about 54K of the complete +bank are actually usable for applications. + +Special locations: + +<descrip> + <tag/Stack/ + The C runtime stack is located at $FF81 and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing CBM 510 specific code may use the <tt/cbm510.h/ or +<tt/cbm.h/ header files. Using the later may be an option when writing code +for more than one CBM platform, since it includes <tt/cbm510.h/ and declares +several functions common to all CBM platforms. + +<sect1>CBM 510 specific functions<p> + +The functions listed below are special for the CBM 510. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>peekbsys +<item>peekwsys +<item>pokebsys +<item>pokewsys +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/cbm510.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can +therefore not be accessed like on other platforms. Please use one of the +<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to +access the I/O chips. Direct reads and writes to the structures named below +will <em>not</em> work! + +<descrip> + + <tag><tt/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC II (the graphics + controller). See the <tt/_vic2.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/SID/</tag> + The <tt/SID/ structure allows access to the SID (the sound interface + device). See the <tt/_sid.h/ header file located in the include directory + for the declaration of the structure. + + <tag><tt/ACIA/</tag> + Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable. + See the <tt/_6551.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/CIA/</tag> + Access to the CIA chip is available via the <tt/CIA/ variable. See the + <tt/_6526.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/TPI1, TPI2/</tag> + The two 6525 triport chips may be accessed by using this variable. See the + <tt/_6525.h/ header file located in the include directory for the + declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the Commodore 510. + + +<sect1>Extended memory drivers<p> + +<descrip> + <tag><tt/cbm510-ram.emd (cbm510_ram)/</tag> + A driver for the RAM in bank 1. Supports up to 255 pages with 256 bytes + each. +</descrip><p> + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/cbm510-std.joy (cbm510_stdjoy)/</tag> + Supports up to two standard joysticks connected to the joysticks port of + the Commodore 510. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Commodore 510. + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/cbm510-std.ser (cbm510_stdser)/</tag> + Driver for the 6551 ACIA chip built into the Commodore 510. Supports up to + 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. + Note that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts flow + control because of a full buffer. + +</descrip><p> + + +<sect>Limitations<label id="limitations"><p> + + +<sect1>Kernal and hardware access<p> + +Since the program runs in bank 0, and the kernal and all I/O chips are located +in bank 15, calling ROM routines or accessing hardware needs special code. The +cc65 runtime implements wrappers for all functions in the kernal jump table. +While this simplifies things, it should be noted that the wrappers do have +quite an impact on performance: A cross bank call has an extra 300µs +penalty added by the wrapper. + +<sect1>Interrupts<p> + +Compiled programs contain an interrupt handler that runs in the program bank. +This has several advantages, one of them being performance (see cross bank +call overhead mentioned above). However, this introduces one problem: +Interrupts are lost while the CPU executes code in the kernal bank. As a +result, the clock may go wrong and (worse) serial interrupts may get lost. + +Since the cc65 runtime does only call the kernal for disk I/O, this means that +a program should not do file I/O while it depends on interrupts. + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line argument passing is currently not supported for the Commodore +510. + + +<sect1>Program return code<p> + +The program return code (signed char) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupt handlers<p> + +The runtime for the Commodore 510 uses routines marked as <tt/.INTERRUPTOR/ +for interrupt handlers. Such routines must be written as simple machine +language subroutines and will be called automatically by the interrupt handler +code when they are linked into a program. See the discussion of the +<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/cbm610.sgml b/doc/cbm610.sgml new file mode 100644 index 000000000..5acb38a1a --- /dev/null +++ b/doc/cbm610.sgml @@ -0,0 +1,300 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore 610 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-16 + +<abstract> +An overview over the Commodore 610 runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the CBM 610 runtime system as it comes with +the cc65 C compiler. It describes the memory layout, CBM 610 specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that CBM 610 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + +In addition to the Commodore 610 (named B40 in the U.S.), several other +machines are supported by this cc65 target, since they have identical +hardware: The Commodore 620 and 630 (more memory, additional coprocessor +card), and the Commodore 710, 720 and 730 (same hardware in another case with +a builtin monitor). + + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Commodore +610 target is a machine language program with a one line BASIC stub, which +transfers control to the machine language running in bank 1. This means that a +program can be loaded as BASIC program and started with RUN. It is of course +possible to change this behaviour by using a modified startup file and linker +config. + + +<sect>Memory layout<p> + +cc65 generated programs for the Commodore 610 run in bank 1, the memory bank +reserved for BASIC programs. Since there are no ROMs in this memory bank, +kernal subroutines are either emulated or called by bank switching, which has +the disadvantage of being slow compared to a direct call. + +The default memory configuration for the CBM 610 allocates all memory between +$0002 and $FFF0 in bank 1 for the compiled program. Some space +in low memory is lost, because a separate hardware stack is set up in page 1, +and the kernal replacement functions need some more memory locations. A few +more bytes are lost in high memory, because the runtime sets up a CBM +compatible jump table at $FF81. The main startup code is located at +$0400, so about 63K of the complete bank are actually usable for +applications. + +Special locations: + +<descrip> + <tag/Stack/ + The C runtime stack is located at $FF81 and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing CBM 610 specific code may use the <tt/cbm610.h/ or +<tt/cbm.h/ header files. Using the later may be an option when writing code +for more than one CBM platform, since it includes <tt/cbm610.h/ and declares +several functions common to all CBM platforms. + +<sect1>CBM 610 specific functions<p> + +The functions listed below are special for the CBM 610. See the <htmlurl +url="funcref.html" name="function reference"> for declaration and usage. + +<itemize> +<item>peekbsys +<item>peekwsys +<item>pokebsys +<item>pokewsys +</itemize> + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/cbm610.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<bf>Note:</bf> All I/O chips are located in the system bank (bank 15) and can +therefore not be accessed like on other platforms. Please use one of the +<tt/peekbsys/, <tt/peekwsys/, <tt/pokebsys/ and <tt/pokewsys/ functions to +access the I/O chips. Direct reads and writes to the structures named below +will <em>not</em> work! + +<descrip> + + <tag><tt/CRTC/</tag> + The <tt/CRTC/ structure allows access to the CRTC (the video controller). + See the <tt/_6545.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/SID/</tag> The <tt/SID/ structure allows access to the SID (the + sound interface device). See the <tt/_sid.h/ header file located in the + include directory for the declaration of the structure. + + <tag><tt/ACIA/</tag> + Access to the ACIA (the RS232 chip) is available via the <tt/ACIA/ variable. + See the <tt/_6551.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/CIA/</tag> + Access to the CIA chip is available via the <tt/CIA/ variable. See the + <tt/_6526.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/TPI1, TPI2/</tag> + The two 6525 triport chips may be accessed by using this variable. See the + <tt/_6525.h/ header file located in the include directory for the + declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the Commodore 610 (and since +the machine has no graphics capabilities, chances for a graphics driver aren't +really good:-). + + +<sect1>Extended memory drivers<p> + +<descrip> + <tag><tt/cbm610-ram.emd (cbm610_ram)/</tag> + A driver for the RAM in bank 2. Supports up to 255 pages with 256 bytes + each. +</descrip><p> + + +<sect1>Joystick drivers<p> + +The Commodore 610 is a business machine and doesn't have joystick ports. There +are no drivers for the non existing ports available. + + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/cbm610-std.ser (cbm610_stdser)/</tag> + Driver for the 6551 ACIA chip built into the Commodore 610. Supports up to + 19200 baud, hardware flow control (RTS/CTS) and interrupt driven receives. + Note that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts flow + control because of a full buffer. + +</descrip><p> + + +<sect>Limitations<label id="limitations"><p> + + +<sect1>Kernal and hardware access<p> + +Since the program runs in bank 1, and the kernal and all I/O chips are located +in bank 15, calling ROM routines or accessing hardware needs special code. The +cc65 runtime implements wrappers for all functions in the kernal jump table. +While this simplifies things, it should be noted that the wrappers do have +quite an impact on performance: A cross bank call has an extra 300µs +penalty added by the wrapper. + +<sect1>Interrupts<p> + +Compiled programs contain an interrupt handler that runs in the program bank. +This has several advantages, one of them being performance (see cross bank +call overhead mentioned above). However, this introduces one problem: +Interrupts are lost while the CPU executes code in the kernal bank. As a +result, the clock may go wrong and (worse) serial interrupts may get lost. + +Since the cc65 runtime does only call the kernal for disk I/O, this means that +a program should not do file I/O while it depends on interrupts. + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line argument passing is currently not supported for the Commodore +610. + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupt handlers<p> + +The runtime for the Commodore 610 uses routines marked as <tt/.INTERRUPTOR/ +for interrupt handlers. Such routines must be written as simple machine +language subroutines and will be called automatically by the interrupt handler +code when they are linked into a program. See the discussion of the +<tt/.CONDES/ feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/cc65.sgml b/doc/cc65.sgml new file mode 100644 index 000000000..bb1303909 --- /dev/null +++ b/doc/cc65.sgml @@ -0,0 +1,1386 @@ +<!doctype linuxdoc system> + +<article> +<title>cc65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2000-09-03, 2001-10-02, 2005-08-01 + +<abstract> +cc65 is a C compiler for 6502 targets. It supports several 6502 based home +computers like the Commodore and Atari machines, but it is easily retargetable. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + + +<sect>Overview<p> + +cc65 was originally a C compiler for the Atari 8-bit machines written by +John R. Dunning. In prior releases I've described the compiler by listing +up the changes made by me. I have made many more changes in the meantime +(and rewritten major parts of the compiler), so I will no longer do that, +since the list would be too large and of no use to anyone. Instead I will +describe the compiler in respect to the ANSI/ISO C standard. + +There are separate documents named <url url="library.html"> and <url +url="funcref.html"> that cover the library that is available for the compiler. +If you know C, and are interested in doing actual programming, the library +documentation is probably of much more use than this document. + +If you need some hints for getting the best code out of the compiler, you +may have a look at <url url="coding.html"> which covers some code generation +issues. + + + +<sect>Usage<p> + +The compiler translates C files into files containing assembly code that +may be translated by the ca65 macroassembler (for more information about +the assembler, have a look at <url url="ca65.html">). + + +<sect1>Command line option overview<p> + +The compiler may be called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: cc65 [options] file +Short options: + -Cl Make local variables static + -Dsym[=defn] Define a symbol + -E Stop after the preprocessing stage + -I dir Set an include directory search path + -O Optimize code + -Oi Optimize code, inline more code + -Or Enable register variables + -Os Inline some known functions + -T Include source as comment + -V Print the compiler version number + -W warning[,...] Suppress warnings + -d Debug mode + -g Add debug info to object file + -h Help (this text) + -j Default characters are signed + -mm model Set the memory model + -o name Name the output file + -r Enable register variables + -t sys Set the target system + -v Increase verbosity + +Long options: + --add-source Include source as comment + --bss-name seg Set the name of the BSS segment + --check-stack Generate stack overflow checks + --code-name seg Set the name of the CODE segment + --codesize x Accept larger code by factor x + --cpu type Set cpu type (6502, 65c02) + --create-dep name Create a make dependency file + --create-full-dep name Create a full make dependency file + --data-name seg Set the name of the DATA segment + --debug Debug mode + --debug-info Add debug info to object file + --debug-opt name Debug optimization steps + --dep-target target Use this dependency target + --disable-opt name Disable an optimization step + --enable-opt name Enable an optimization step + --forget-inc-paths Forget include search paths + --help Help (this text) + --include-dir dir Set an include directory search path + --list-opt-steps List all optimizer steps and exit + --list-warnings List available warning types for -W + --local-strings Emit string literals immediately + --memory-model model Set the memory model + --register-space b Set space available for register variables + --register-vars Enable register variables + --rodata-name seg Set the name of the RODATA segment + --signed-chars Default characters are signed + --standard std Language standard (c89, c99, cc65) + --static-locals Make local variables static + --target sys Set the target system + --verbose Increase verbosity + --version Print the compiler version number + --writable-strings Make string literals writable +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <label id="option-bss-name"> + <tag><tt>--bss-name seg</tt></tag> + + Set the name of the bss segment. See also <tt/<ref id="pragma-bss-name" + name="#pragma bss-name">/. + + + <label id="option-check-stack"> + <tag><tt>--check-stack</tt></tag> + + Tells the compiler to generate code that checks for stack overflows. See + <tt/<ref id="pragma-check-stack" name="#pragma check-stack">/ for an + explanation of this feature. + + + <label id="option-code-name"> + <tag><tt>--code-name seg</tt></tag> + + Set the name of the code segment. See also <tt/<ref id="pragma-code-name" + name="#pragma code-name">/ + + + <label id="option-codesize"> + <tag><tt>--codesize x</tt></tag> + + This options allows finer control about speed vs. size decisions in the code + generation and optimization phases. It gives the allowed size increase + factor (in percent). The default is 100 when not using <tt/-Oi/ and 200 when + using <tt/-Oi/ (<tt/-Oi/ is the same as <tt/-O --codesize 200/). + + + <label id="option--cpu"> + <tag><tt>--cpu CPU</tt></tag> + + Set the CPU, the compiler generates code for. You may specify "6502" or + "65C02" as the CPU. The default depends on the selected target (see option + <tt/<ref id="option-t" name="-t">/). It is the 6502 CPU for most targets or + if no target has been set. Specifying 65C02 will use a few 65C02 + instructions when generating code. Don't expect too much from this option: + In most cases the difference in size and speed is just 1-2%. + + + <label id="option-create-dep"> + <tag><tt>--create-dep name</tt></tag> + + Tells the compiler to generate a file containing the dependency list for the + compiled module in makefile syntax. The output is written to a file with the + given name. The output does not include system include files (in angle + brackets). + + + <label id="option-create-full-dep"> + <tag><tt>--create-full-dep name</tt></tag> + + Tells the compiler to generate a file containing the dependency list for the + compiled module in makefile syntax. The output is written to a file with the + given name. The output does include system include files (in angle + brackets). + + + <label id="option-data-name"> + <tag><tt>--data-name seg</tt></tag> + + Set the name of the data segment. See also <tt/<ref id="pragma-data-name" + name="#pragma data-name">/ + + + <tag><tt>-d, --debug</tt></tag> + + Enables debug mode, something that should not be needed for mere + mortals:-) + + + <label id="option-dep-target"> + <tag><tt>--dep-target target</tt></tag> + + When generating a dependency file, don't use the actual output file as the + target of the dependency, but the file specified with this option. The + option has no effect if neither <tt/<ref id="option-create-dep" + name="--create-dep">/ nor <tt/<ref id="option-create-full-dep" + name="--create-full-dep">/ is specified. + + + <tag><tt>-D sym[=definition]</tt></tag> + + Define a macro on the command line. If no definition is given, the macro + is defined to the value "1". + + + <tag><tt>--forget-inc-paths</tt></tag> + + Forget the builtin include paths. This is most useful when building + customized C or runtime libraries, in which case the standard header + files should be ignored. + + + <tag><tt>-g, --debug-info</tt></tag> + + This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the + generated assembler code. This will cause the assembler to include all + symbols in a special section in the object file. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option-list-warnings"> + <tag><tt>--list-warnings</tt></tag> + + List the names of warning types available for use with <tt><ref + id="option-W" name="-W"></tt>. + + + <label id="option-local-strings"> + <tag><tt>--local-strings</tt></tag> + + Emit string literals into the rodata segment as soon as they're encountered + in the source (even if you do nothing but get the sizeof those strings). The + default is to keep string literals until end of assembly, merge read only + literals if possible, and then output the literals into the data or rodata + segment that is active at that point. Use of this option prevents merging of + duplicate strings, but the options that change the name of one of the data + segments will work. + + You can also use <tt><ref id="pragma-local-strings" + name="#pragma local-strings"></tt> for fine grained control. + + + <tag><tt>-o name</tt></tag> + + Specify the name of the output file. If you don't specify a name, the + name of the C input file is used, with the extension replaced by ".s". + + + <label id="option-register-vars"> + <tag><tt>-r, --register-vars</tt></tag> + + <tt/-r/ will make the compiler honor the <tt/register/ keyword. Local + variables may be placed in registers (which are actually zero page + locations). There is some overhead involved with register variables, since + the old contents of the registers must be saved and restored. Since register + variables are of limited use without the optimizer, there is also a combined + switch: <tt/-Or/ will enable both, the optimizer and register variables. + + For more information about register variables see <ref id="register-vars" + name="register variables">. + + The compiler setting can also be changed within the source file by using + <tt/<ref id="pragma-register-vars" name="#pragma register-vars">/. + + + <label id="option-register-space"> + <tag><tt>--register-space</tt></tag> + + This option takes a numeric parameter and is used to specify, how much + zero page register space is available. Please note that just giving this + option will not increase or decrease by itself, it will just tell the + compiler about the available space. You will have to allocate that space + yourself using an assembler module with the necessary allocations, and a + linker configuration that matches the assembler module. The default value + for this option is 6 (bytes). + + If you don't know what all this means, please don't use this option. + + + <label id="option-rodata-name"> + <tag><tt>--rodata-name seg</tt></tag> + + Set the name of the rodata segment (the segment used for readonly data). + See also <tt/<ref id="pragma-rodata-name" name="#pragma rodata-name">/ + + <label id="option-signed-chars"> + <tag><tt>-j, --signed-chars</tt></tag> + + Using this option, you can make the default characters signed. Since the + 6502 has no provisions for sign extending characters (which is needed on + almost any load operation), this will make the code larger and slower. A + better way is to declare characters explicitly as "signed" if needed. You + can also use <tt><ref id="pragma-signed-chars" + name="#pragma signed-chars"></tt> for better control of this option. + + + <label id="option--standard"> + <tag><tt>--standard std</tt></tag> + + This option allows to set the language standard supported. The argument is + one of + <descrip> + <tag/c89/ + This disables anything that is illegal in C89/C90. Among those things + are <tt>//</tt> comments and the non-standard keywords without + underscores. Please note that cc65 is not a fully C89 compliant compiler + despite this option. A few more things (like floats) are missing. + + <tag/c99/ + This enables a few features from the C99 standard. With this option, + <tt>//</tt> comments are allowed. It will also cause warnings and even + errors in a few situations that are allowed with <tt/--standard c89/. + For example, a call to a function without a prototype is an error in + this mode. + + <tag/cc65/ + This is the default mode. It is like c99 mode, but additional features + are enabled. Among these are "void data", non-standard keywords without + the underlines, unnamed function parameters and the requirement for + main() to return an int. + </descrip> + + Please note that the compiler does not support the C99 standard and never + will. c99 mode is actually c89 mode with a few selected C99 extensions. + + + <label id="option-t"> + <tag><tt>-t target, --target target</tt></tag> + + This option is used to set the target system. The target system determines + the character set that is used for strings and character constants and the + default CPU. The CPU setting can be overriden by use of the <tt/<ref + id="option--cpu" name="--cpu">/ option. + + The following target systems are supported: + + <itemize> + <item>none + <item>apple2 + <item>apple2enh + <item>atari + <item>atmos + <item>c16 (works also for the c116 with memory up to 32K) + <item>c64 + <item>c128 + <item>cbm510 (CBM-II series with 40 column video) + <item>cbm610 (all CBM-II II computers with 80 column video) + <item>geos-apple + <item>geos-cbm + <item>lunix + <item>lynx + <item>nes + <item>pet (all CBM PET systems except the 2001) + <item>plus4 + <item>supervision + <item>vic20 + </itemize> + + <tag><tt>-v, --verbose</tt></tag> + + Using this option, the compiler will be somewhat more verbose if errors + or warnings are encountered. + + + <label id="option-writable-strings"> + <tag><tt>--writable-strings</tt></tag> + + Make string literals writable by placing them into the data segment instead + of the rodata segment. You can also use <tt><ref id="pragma-writable-strings" + name="#pragma writable-strings"></tt> to control this option from within + the source file. + + + <label id="option-static-locals"> + <tag><tt>-Cl, --static-locals</tt></tag> + + Use static storage for local variables instead of storage on the stack. + Since the stack is emulated in software, this gives shorter and usually + faster code, but the code is no longer reentrant. The difference between + <tt/-Cl/ and declaring local variables as static yourself is, that + initializer code is executed each time, the function is entered. So when + using + + <tscreen><verb> + void f (void) + { + unsigned a = 1; + ... + } + </verb></tscreen> + + the variable <tt/a/ will always have the value <tt/1/ when entering the + function and using <tt/-Cl/, while in + + <tscreen><verb> + void f (void) + { + static unsigned a = 1; + .... + } + </verb></tscreen> + + the variable <tt/a/ will have the value <tt/1/ only the first time that the + function is entered, and will keep the old value from one call of the + function to the next. + + You may also use <tt><ref id="pragma-static-locals" + name="#pragma static-locals"></tt> to change this setting in your + sources. + + + <label id="option-include-dir"> + <tag><tt>-I dir, --include-dir dir</tt></tag> + + Set a directory where the compiler searches for include files. You may + use this option multiple times to add more than one directory to the + search list. + + + <label id="option-O"> + <tag><tt>-O, -Oi, -Or, -Os</tt></tag> + + Enable an optimizer run over the produced code. + + Using <tt/-Oi/, the code generator will inline some code where otherwise a + runtime functions would have been called, even if the generated code is + larger. This will not only remove the overhead for a function call, but will + make the code visible for the optimizer. <tt/-Oi/ is an alias for + <tt/-O --codesize 200/. + + <tt/-Or/ will make the compiler honor the <tt/register/ keyword. Local + variables may be placed in registers (which are actually zero page + locations). See also the <tt/<ref id="option-register-vars" + name="--register-vars">/ command line option, and the <ref + id="register-vars" name="discussion of register variables"> below. + + Using <tt/-Os/ will force the compiler to inline some known functions from + the C library like strlen. Note: This has two consequences: + <p> + <itemize> + <item>You may not use names of standard C functions in your own code. If you + do that, your program is not standard compliant anyway, but using + <tt/-Os/ will actually break things. + <p> + <item>The inlined string and memory functions will not handle strings or + memory areas larger than 255 bytes. Similarly, the inlined <tt/is..()/ + functions will not work with values outside the char. range (such as + <tt/EOF/). + <p> + </itemize> + <p> + It is possible to concatenate the modifiers for <tt/-O/. For example, to + enable register variables and inlining of known functions, you may use + <tt/-Ors/. + + + <tag><tt>-T, --add-source</tt></tag> + + This include the source code as comments in the generated code. This is + normally not needed. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the compiler. When submitting a bug report, + please include the operating system you're using, and the compiler + version. + + + <label id="option-W"> + <tag><tt>-W name[,name]</tt></tag> + + This option allows to control warnings generated by the compiler. It is + followed by a comma separated list of warnings that should be enabled or + disabled. To disable a warning, its name is prefixed by a minus sign. If + no such prefix exists, or the name is prefixed by a plus sign, the warning + is enabled. + + The following warning names are currently recognized: + <descrip> + <tag><tt/const-comparison/</tag> + Warn if the result of a comparison is constant. + <tag><tt/error/</tag> + Treat all warnings as errors. + <tag><tt/no-effect/</tag> + Warn about statements that don't have an effect. + <tag><tt/struct-param/</tag> + Warn when passing structs by value. + <tag><tt/unknown-pragma/</tag> + Warn about known #pragmas. + <tag><tt/unused-label/</tag> + Warn about unused labels. + <tag><tt/unused-param/</tag> + Warn about unused function parameters. + <tag><tt/unused-var/</tag> + Warn about unused variables. + </descrip> + + The full list of available warning names may be retrieved by using the + option <tt><ref id="option-list-warnings" name="--list-warnings"></tt>. + + You may also use <tt><ref id="pragma-warn" name="#pragma warn"></tt> to + control this setting for smaller pieces of code from within your code. + +</descrip><p> + + +<sect>Input and output<p> + +The compiler will accept one C file per invocation and create a file with +the same base name, but with the extension replaced by ".s". The output +file contains assembler code suitable for the use with the ca65 macro +assembler. + +Include files in single quotes are searched in the following places: +<enum> +<item>The current directory. +<item>The value of the environment variable <tt/CC65_INC/ if it is defined. +<item>Any directory added with the <tt/-I/ option on the command line. +</enum> + +Include files in angle brackets are searched in the following places: +<enum> +<item>A compiled in directory which is often <tt>/usr/lib/cc65/include</tt> on + Linux systems. +<item>The value of the environment variable <tt/CC65_INC/ if it is defined. +<item>A subdirectory named <tt/include/ of the directory defined in the + environment variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt/-I/ option on the command line. +</enum> + + + +<sect>Differences to the ISO standard<p> + +Apart from the things listed below, the compiler does support additional +keywords, has several functions in the standard headers with names outside the +reserved namespace and a few syntax extensions. All these can be disabled with +the <tt><ref id="option--standard" name="--standard"></tt> command line +option. Its use for maximum standards compatibility is advised. + +Here is a list of differences between the language, the compiler accepts, +and the one defined by the ISO standard: + +<itemize> + +<item> The datatypes "float" and "double" are not available. + <p> +<item> C Functions may not return structs (or unions), and structs may not + be passed as parameters by value. However, struct assignment *is* + possible. + <p> +<item> Part of the C library is available only with fastcall calling + conventions (see below). It means that you must not mix pointers to + those functions with pointers to user-written, not-fastcall functions. + <p> +<item> The <tt/volatile/ keyword doesn't have an effect. This is not as bad + as it sounds, since the 6502 has so few registers that it isn't + possible to keep values in registers anyway. + <p> +</itemize> + +There may be some more minor differences I'm currently not aware of. The +biggest problem is the missing float data type. With this limitation in +mind, you should be able to write fairly portable code. + + + +<sect>Extensions<p> + +This cc65 version has some extensions to the ISO C standard. + +<itemize> + +<item> The compiler allows to insert assembler statements into the output + file. The syntax is + + <tscreen><verb> + asm (<string literal>[, optional parameters]) ; + </verb></tscreen> + or + <tscreen><verb> + __asm__ (<string literal>[, optional parameters]) ; + </verb></tscreen> + + The first form is in the user namespace and is disabled if the <tt/-A/ + switch is given. + + There is a whole section covering inline assembler statements, + <ref id="inline-asm" name="see there">. + <p> + +<item> There is a special calling convention named "fastcall". + The syntax for a function declaration using fastcall is + + <tscreen><verb> + <return type> fastcall <function name> (<parameter list>) + </verb></tscreen> + or + <tscreen><verb> + <return type> __fastcall__ <function name> (<parameter list>) + </verb></tscreen> + An example would be + <tscreen><verb> + void __fastcall__ f (unsigned char c) + </verb></tscreen> + The first form of the fastcall keyword is in the user namespace and can + therefore be disabled with the <tt><ref id="option--standard" + name="--standard"></tt> command line option. + + For functions declared as <tt/fastcall/, the rightmost parameter is not + pushed on the stack but left in the primary register when the function + is called. This will reduce the cost when calling assembler functions + significantly, especially when the function itself is rather small. + <p> + +<item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/. + Both refer to the primary register that is used by the compiler to + evaluate expressions or return function results. <tt/__AX__/ is of + type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/ + respectively. The pseudo variables may be used as lvalue and rvalue as + every other variable. They are most useful together with short + sequences of assembler code. For example, the macro + + <tscreen><verb> + #define hi(x) \ + (__AX__ = (x), \ + asm ("txa"), \ + asm ("ldx #$00"), \ + __AX__) + </verb></tscreen> + + will give the high byte of any unsigned value. + <p> + +<item> Inside a function, the identifier <tt/__func__/ gives the name of the + current function as a string. Outside of functions, <tt/__func__/ is + undefined. + Example: + + <tscreen><verb> + #define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s); + </verb></tscreen> + + The macro will print the name of the current function plus a given + string. + <p> + +<item> cc65 allows the initialization of <tt/void/ variables. This may be + used to create variable structures that are more compatible with + interfaces written for assembler languages. Here is an example: + + <tscreen><verb> + void GCmd = { (char)3, (unsigned)0x2000, (unsigned)0x3000 }; + </verb></tscreen> + + This will be translated as follows: + + <tscreen><verb> + _GCmd: + .byte 3 + .word $2000 + .word $3000 + </verb></tscreen> + + Since the variable is of type <tt/void/ you may not use it as is. + However, taking the address of the variable results in a <tt/void*/ + which may be passed to any function expecting a pointer. + + See the <url url="geos.html" name="GEOS library document"> for examples + on how to use this feature. + <p> + +<item> cc65 implements flexible array struct members as defined in the C99 ISO + standard. As an extension, these fields may be initialized. There are + several exceptions, however (which is probably the reason why the + standard does not define this feature, because it is highly + unorthogonal). Flexible array members cannot be initialized ... + + <itemize> + <item>... when defining an array of structs with flexible + members. + <item>... if such a struct is a member field of another struct + which is not the last field. + <item>... if the struct which contains a flexible array member is + declared as <tt/register/, and the size and compiler settings + do allow the compiler actually to place the struct into the + register bank in the zero page. + </itemize> + + Please note that -- as defined in the ISO C standard -- the <tt/sizeof/ + operator returns the struct size with the flexible array member having + size zero, even if it is initialized. + <p> + +</itemize> +<p> + + +<sect>Predefined macros<p> + +The compiler defines several macros at startup: + +<descrip> + <tag><tt>__APPLE2__</tt></tag> + + This macro is defined if the target is the Apple ][ (-t apple2). + + <tag><tt>__APPLE2ENH__</tt></tag> + + This macro is defined if the target is the enhanced Apple //e (-t apple2enh). + + <tag><tt>__ATARI__</tt></tag> + + This macro is defined if the target is one of the Atari computers + (400/800/130XL/800XL). + + <tag><tt>__ATMOS__</tt></tag> + + This macro is defined if the target is the Oric Atmos (-t atmos). + + <tag><tt>__C128__</tt></tag> + + This macro is defined if the target is the c128 (-t c128). + + <tag><tt>__C16__</tt></tag> + + This macro is defined if the target is the c16 (-t c16). + + <tag><tt>__C64__</tt></tag> + + This macro is defined if the target is the c64 (-t c64). + + <tag><tt>__CBM__</tt></tag> + + This macro is defined if the target system is one of the CBM targets. + + <tag><tt>__CBM510__</tt></tag> + + This macro is defined if the target is the CBM 500 series of computers. + + <tag><tt>__CBM610__</tt></tag> + + This macro is defined if the target is one of the CBM 600/700 family of + computers (called B series in the US). + + <tag><tt>__CC65__</tt></tag> + + This macro is always defined. Its value is the version number of the + compiler in hex. For example, version 2.10.1 of the compiler has this macro + defined as <tt/0x02A1/. + + <tag><tt>__CC65_STD__</tt></tag> + + This macro is defined to one of the following depending on the <tt><ref + id="option--standard" name="--standard"></tt> command line option: + <itemize> + <item><tt/__CC65_STD_C89__/ + <item><tt/__CC65_STD_C99__/ + <item><tt/__CC65_STD_CC65__/ + </itemize> + + <tag><tt>__DATE__</tt></tag> + + This macro expands to the date of translation of the preprocessing + translation unit in the form "Mmm dd yyyy". + + <tag><tt>__FILE__</tt></tag> + + This macro expands to a string containing the name of the C source file. + + <tag><tt>__GEOS__</tt></tag> + + This macro is defined if you are compiling for the GEOS system (-t geos). + + <tag><tt>__LINE__</tt></tag> + + This macro expands to the current line number. + + <tag><tt>__LUNIX__</tt></tag> + + This macro is defined if you are compiling for the LUnix system (-t lunix). + + <tag><tt>__LYNX__</tt></tag> + + This macro is defined if the target is the Atari Lynx (-t lynx). + + <tag><tt>__NES__</tt></tag> + + This macro is defined if the target is the NES (-t nes). + + <tag><tt>__OPT__</tt></tag> + + Is defined if the compiler was called with the <tt/-O/ command line option. + + <tag><tt>__OPT_i__</tt></tag> + + Is defined if the compiler was called with the <tt/-Oi/ command line option. + + <tag><tt>__OPT_r__</tt></tag> + + Is defined if the compiler was called with the <tt/-Or/ command line option. + + <tag><tt>__OPT_s__</tt></tag> + + Is defined if the compiler was called with the <tt/-Os/ command line option. + + <tag><tt>__PET__</tt></tag> + + This macro is defined if the target is the PET family of computers (-t pet). + + <tag><tt>__PLUS4__</tt></tag> + + This macro is defined if the target is the plus/4 (-t plus4). + + <tag><tt>__STDC_HOSTED__</tt></tag> + + This macro is expands to the integer constant 1. + + <tag><tt>__SUPERVISION__</tt></tag> + + This macro is defined if the target is the supervision (-t supervision). + + <tag><tt>__TIME__</tt></tag> + + This macro expands to the time of translation of the preprocessing + translation unit in the form "hh:mm:ss". + + <tag><tt>__VIC20__</tt></tag> + + This macro is defined if the target is the vic20 (-t vic20). +</descrip> + + +<sect>#pragmas<label id="pragmas"><p> + +The compiler understands some pragmas that may be used to change code +generation and other stuff. Some of these pragmas understand a special form: +If the first parameter is <tt/push/, the old value is saved onto a stack +before changing it. The value may later be restored by using the <tt/pop/ +parameter with the <tt/#pragma/. + +<sect1><tt>#pragma bss-name ([push,] <name>)</tt><label id="pragma-bss-name"><p> + + This pragma changes the name used for the BSS segment (the BSS segment + is used to store uninitialized data). The argument is a string enclosed + in double quotes. + + Note: The default linker configuration file does only map the standard + segments. If you use other segments, you have to create a new linker + configuration file. + + Beware: The startup code will zero only the default BSS segment. If you + use another BSS segment, you have to do that yourself, otherwise + uninitialized variables do not have the value zero. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma bss-name ("MyBSS") + </verb></tscreen> + + +<sect1><tt>#pragma charmap (<index>, <code>)</tt><label id="pragma-charmap"><p> + + Each literal string and each literal character in the source is translated + by use of a translation table. This translation table is preset when the + compiler is started depending on the target system, for example to map + ISO-8859-1 characters into PETSCII if the target is a commodore machine. + + This pragma allows to change entries in the translation table, so the + translation for individual characters, or even the complete table may be + adjusted. + + Both arguments are assumed to be unsigned characters with a valid range of + 1-255. + + Beware of two pitfalls: + + <itemize> + <item>The character index is actually the code of the character in the + C source, so character mappings do always depend on the source + character set. This means that <tt/#pragma charmap/ is not + portable -- it depends on the build environment. + <item>While it is possible to use character literals as indices, the + result may be somewhat unexpected, since character literals are + itself translated. For this reason I would suggest to avoid + character literals and use numeric character codes instead. + </itemize> + + Example: + <tscreen><verb> + /* Use a space wherever an 'a' occurs in ISO-8859-1 source */ + #pragma charmap (0x61, 0x20); + </verb></tscreen> + + +<sect1><tt>#pragma check-stack ([push,] on|off)</tt><label id="pragma-check-stack"><p> + + Tells the compiler to insert calls to a stack checking subroutine to detect + stack overflows. The stack checking code will lead to somewhat larger and + slower programs, so you may want to use this pragma when debugging your + program and switch it off for the release version. If a stack overflow is + detected, the program is aborted. + + If the argument is "off", stack checks are disabled (the default), otherwise + they're enabled. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + +<sect1><tt>#pragma code-name ([push,] <name>)</tt><label id="pragma-code-name"><p> + + This pragma changes the name used for the CODE segment (the CODE segment + is used to store executable code). The argument is a string enclosed in + double quotes. + + Note: The default linker configuration file does only map the standard + segments. If you use other segments, you have to create a new linker + configuration file. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma code-name ("MyCODE") + </verb></tscreen> + + +<sect1><tt>#pragma codesize ([push,] <int>)</tt><label id="pragma-codesize"><p> + + This pragma allows finer control about speed vs. size decisions in the code + generation and optimization phase. It gives the allowed size increase factor + (in percent). The default is can be changed by use of the <tt/<ref + id="option-codesize" name="--codesize">/ compiler option. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma data-name ([push,] <name>)</tt><label id="pragma-data-name"><p> + + This pragma changes the name used for the DATA segment (the DATA segment + is used to store initialized data). The argument is a string enclosed in + double quotes. + + Note: The default linker configuration file does only map the standard + segments. If you use other segments, you have to create a new linker + configuration file. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma data-name ("MyDATA") + </verb></tscreen> + + +<sect1><tt>#pragma local-strings ([push,] on|off)</tt><label id="pragma-local-strings"><p> + + When "on", emit string literals to the data segment when they're encountered + in the source. The default ("off") is to keep string literals until end of + assembly, merge read only literals if possible, and then output the literals + into the data or rodata segment that is active at that point. + + Using this <tt/#pragma/ it is possible to control the behaviour from within + the source. When <tt/#pragma local-strings/ is active, string literals are + output immediately, which means that they go into the currently active data + or rodata segment, but cannot be merged. When inactive, string literals are + remembered and output as a whole when translation is finished. + + +<sect1><tt>#pragma optimize ([push,] on|off)</tt><label id="pragma-optimize"><p> + + Switch optimization on or off. If the argument is "off", optimization is + disabled, otherwise it is enabled. Please note that this pragma only effects + whole functions. The setting in effect when the function is encountered will + determine if the generated code is optimized or not. + + Optimization and code generation is also controlled by the <ref + id="pragma-codesize" name="codesize pragma">. + + The default is "off", but may be changed with the <tt/<ref name="-O" + id="option-O">/ compiler option. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma rodata-name ([push,] <name>)</tt><label id="pragma-rodata-name"><p> + + This pragma changes the name used for the RODATA segment (the RODATA + segment is used to store readonly data). The argument is a string + enclosed in double quotes. + + Note: The default linker configuration file does only map the standard + segments. If you use other segments, you have to create a new linker + configuration file. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma rodata-name ("MyRODATA") + </verb></tscreen> + + +<sect1><tt>#pragma regvaraddr ([push,] on|off)</tt><label id="pragma-regvaraddr"><p> + + The compiler does not allow to take the address of register variables. + The regvaraddr pragma changes this. Taking the address of a register + variable is allowed after using this pragma with "on" as argument. + Using "off" as an argument switches back to the default behaviour. + + Beware: The C standard does not allow taking the address of a variable + declared as register. So your programs become non-portable if you use + this pragma. In addition, your program may not work. This is usually the + case if a subroutine is called with the address of a register variable, + and this subroutine (or a subroutine called from there) uses + register variables. So be careful with this #pragma. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + Example: + <tscreen><verb> + #pragma regvaraddr(on) /* Allow taking the address + * of register variables + */ + </verb></tscreen> + + +<sect1><tt>#pragma register-vars ([push,] on|off)</tt><label id="pragma-register-vars"><p> + + Enables or disables use of register variables. If register variables are + disabled (the default), the <tt/register/ keyword is ignored. Register + variables are explained in more detail in <ref id="register-vars" name="a separate + chapter">. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma signed-chars ([push,] on|off)</tt><label id="pragma-signed-chars"><p> + + Changes the signedness of the default character type. If the argument is + "on", default characters are signed, otherwise characters are unsigned. The + compiler default is to make characters unsigned since this creates a lot + better code. This default may be overridden by the <tt/<ref + name="--signed-chars" id="option-signed-chars">/ command line option. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma static-locals ([push,] on|off)</tt><label id="pragma-static-locals"<p> + + Use variables in the bss segment instead of variables on the stack. This + pragma changes the default set by the compiler option <tt/<ref + name="--static-locals" id="option-static-locals">/. If the argument is "on", + local variables are allocated in the BSS segment, leading to shorter and in + most cases faster, but non-reentrant code. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma warn (name, [push,] on|off)</tt><label id="pragma-warn"><p> + + Switch compiler warnings on or off. "name" is the name of a warning (see the + <tt/<ref name="-W" id="option-W">/ compiler option for a list). The name is + either followed by "pop", which restores the last pushed state, or by "on" or + "off", optionally preceeded by "push" to push the current state before + changing it. + + Example: + <tscreen><verb> + /* Don't warn about the unused parameter in function func */ + #pragma warn (unused-param, push, off) + static int func (int unused) + { + return 0; + } + #pragma warn (unused-param, pop) + </verb></tscreen> + +<sect1><tt>#pragma writable-strings ([push,] on|off)</tt><label id="pragma-writable-strings"><p> + + Changes the storage location of string literals. For historical reasons, + the C standard defines that string literals are of type "char[]", but + writing to such a literal causes undefined behaviour. Most compilers + (including cc65) place string literals in the read-only data segment, which + may cause problems with old C code that writes to string literals. + + Using this pragma (or the corresponding command line option <tt/<ref + name="--writable-strings" id="option-writable-strings">/) causes the + literals to be placed in the data segment so they can be written to without + worry. + + The <tt/#pragma/ understands the push and pop parameters as explained above. + + +<sect1><tt>#pragma zpsym (<name>)</tt><p> + + Tell the compiler that the -- previously as external declared -- symbol with + the given name is a zero page symbol (usually from an assembler file). + The compiler will create a matching import declaration for the assembler. + + Example: + <tscreen><verb> + extern int foo; + #pragma zpsym ("foo"); /* foo is in the zeropage */ + </verb></tscreen> + + + + +<sect>Register variables<label id="register-vars"><p> + +The runtime for all supported platforms has 6 bytes of zero page space +available for register variables (this could be increased, but I think it's a +good value). So you can declare register variables up to a total size of 6 per +function. The compiler will allocate register space on a "first come, first +served" base and convert any <tt/register/ declarations that exceed the +available register space silently to <tt/auto/. Parameters can also be +declared as <tt/register/, this will in fact give slightly shorter code than +using a register variable. + +Since a function must save the current values of the registers on entry and +restore them on exit, there is an overhead associated with register variables, +and this overhead is quite high (about 20 bytes per variable). This means that +just declaring anything as <tt/register/ is not a good idea. + +The best use for register variables are pointers, especially those that point +to structures. The magic number here is about 3 uses of a struct field: If the +function contains this number or even more, the generated code will be usually +shorter and faster when using a register variable for the struct pointer. The +reason for this is that the register variable can in many cases be used as a +pointer directly. Having a pointer in an auto variable means that this pointer +must first be copied into a zero page location, before it can be dereferenced. + +Second best use for register variables are counters. However, there is not +much difference in the code generated for counters, so you will need at least +100 operations on this variable (for example in a loop) to make it worth the +trouble. The only savings you get here are by the use of a zero page variable +instead of one on the stack or in the data segment. + +Register variables must be explicitly enabled, either by using <tt/<ref +name="-Or" id="option-O">/ or <tt/<ref name="--register-vars" +id="option-register-vars">/ on the command line or by use of <tt/<ref +name="#pragma register-vars" id="pragma-register-vars">/. Register variables +are only accepted on function top level, register variables declared in +interior blocks are silently converted to <tt/auto/. With register variables +disabled, all variables declared as <tt/register/ are actually auto variables. + +Please take care when using register variables: While they are helpful and can +lead to a tremendous speedup when used correctly, improper usage will cause +bloated code and a slowdown. + + + +<sect>Inline assembler<label id="inline-asm"><p> + +The compiler allows to insert assembler statements into the output file. The +syntax is + +<tscreen><verb> + asm (<string literal>[, optional parameters]) ; +</verb></tscreen> +or +<tscreen><verb> + __asm__ (<string literal>[, optional parameters]) ; +</verb></tscreen> +<p> + +The first form is in the user namespace and is disabled by <tt><ref +id="option--standard" name="--standard"></tt> if the argument is not <tt/cc65/. + +The asm statement may be used inside a function and on global file level. An +inline assembler statement is a primary expression, so it may also be used as +part of an expression. Please note however that the result of an expression +containing just an inline assembler statement is always of type <tt/void/. + +The contents of the string literal are preparsed by the compiler and inserted +into the generated assembly output, so that the can be further processed by +the backend and especially the optimizer. For this reason, the compiler does +only allow regular 6502 opcodes to be used with the inline assembler. Pseudo +instructions (like <tt/.import/, <tt/.byte/ and so on) are <em/not/ allowed, +even if the ca65 assembler (which is used to translate the generated assembler +code) would accept them. The builtin inline assembler is not a replacement for +the full blown macro assembler which comes with the compiler. + +Note: Inline assembler statements are subject to all optimizations done by the +compiler. There is currently no way to protect an inline assembler statement +from being moved or removed completely by the optimizer. If in doubt, check +the generated assembler output, or disable optimizations. + +The string literal may contain format specifiers from the following list. For +each format specifier, an argument is expected which is inserted instead of +the format specifier before passing the assembly code line to the backend. + +<itemize> + <item><tt/%b/ - Numerical 8-bit value + <item><tt/%w/ - Numerical 16-bit value + <item><tt/%l/ - Numerical 32-bit value + <item><tt/%v/ - Assembler name of a global variable or function + <item><tt/%o/ - Stack offset of a local variable + <item><tt/%g/ - Assembler name of a C label + <item><tt/%s/ - The argument is converted to a string + <item><tt/%%/ - The % sign itself +</itemize><p> + +Using these format specifiers, you can access C <tt/#defines/, variables or +similar stuff from the inline assembler. For example, to load the value of +a C <tt/#define/ into the Y register, one would use + +<tscreen><verb> + #define OFFS 23 + __asm__ ("ldy #%b", OFFS); +</verb></tscreen> + +Or, to access a struct member of a static variable: + +<tscreen><verb> + typedef struct { + unsigned char x; + unsigned char y; + unsigned char color; + } pixel_t; + static pixel_t pixel; + __asm__ ("ldy #%b", offsetof(pixel_t, color)); + __asm__ ("lda %v,y", pixel); +</verb></tscreen> +<p> +The next example shows how to use global variables to exchange data between C +an assembler and how to handle assembler jumps: + +<tscreen><verb> + unsigned char globalSubA, globalSubB, globalSubResult; + + /* return a-b, return 255 if b>a */ + unsigned char sub (unsigned char a, unsigned char b) + { + globalSubA = a; + globalSubB = b; + __asm__ ("sec"); + __asm__ ("lda %v", globalSubA); + __asm__ ("sbc %v", globalSubB); + __asm__ ("bcs %g", jumpSubNoError); + __asm__ ("lda #$FF"); + jumpSubNoError: + __asm__ ("sta %v", globalSubResult); + return globalSubResult; + } +</verb></tscreen> +<p> + +Arrays can also be accessed: + +<tscreen><verb> + unsigned char globalSquareTable[] = { + 0, 1, 4, 9, 16, 25, 36, 49, 64, 81, + 100, 121, 144, 169, 196, 225 + }; + unsigned char globalSquareA, globalSquareResult; + + /* return a*a for a<16, else 255 */ + unsigned char square (unsigned char a) + { + if (a>15){ + return 255; + } + globalSquareA = a; + __asm__ ("ldx %v", globalSquareA); + __asm__ ("lda %v,x", globalSquareTable); + __asm__ ("sta %v", globalSquareResult); + return globalSquareResult; + } +</verb></tscreen> +<p> + +Note: Do not embed the assembler labels that are used as names of global +variables or functions into your asm statements. Code like this + +<tscreen><verb> + int foo; + int bar () { return 1; } + __asm__ ("lda _foo"); /* DON'T DO THAT! */ + ... + __asm__ ("jsr _bar"); /* DON'T DO THAT EITHER! */ +</verb></tscreen> +<p> + +may stop working if the way, the compiler generates these names is changed in +a future version. Instead use the format specifiers from the table above: + +<tscreen><verb> + __asm__ ("lda %v", foo); /* OK */ + ... + __asm__ ("jsr %v", bar); /* OK */ +</verb></tscreen> +<p> + + +<sect>Implementation-defined behavior<p> + +This section describes the behavior of cc65 when the standard describes the +behavior as implementation-defined. + +(to be done) + +<sect>Bugs/Feedback<p> + +If you have problems using the compiler, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +This is the original compiler copyright: + +<tscreen><verb> +-------------------------------------------------------------------------- + -*- Mode: Text -*- + + This is the copyright notice for RA65, LINK65, LIBR65, and other + Atari 8-bit programs. Said programs are Copyright 1989, by John R. + Dunning. All rights reserved, with the following exceptions: + + Anyone may copy or redistribute these programs, provided that: + + 1: You don't charge anything for the copy. It is permissable to + charge a nominal fee for media, etc. + + 2: All source code and documentation for the programs is made + available as part of the distribution. + + 3: This copyright notice is preserved verbatim, and included in + the distribution. + + You are allowed to modify these programs, and redistribute the + modified versions, provided that the modifications are clearly noted. + + There is NO WARRANTY with this software, it comes as is, and is + distributed in the hope that it may be useful. + + This copyright notice applies to any program which contains + this text, or the refers to this file. + + This copyright notice is based on the one published by the Free + Software Foundation, sometimes known as the GNU project. The idea + is the same as theirs, ie the software is free, and is intended to + stay that way. Everybody has the right to copy, modify, and re- + distribute this software. Nobody has the right to prevent anyone + else from copying, modifying or redistributing it. + +-------------------------------------------------------------------------- +</verb></tscreen> + +Small parts of the compiler (parts of the preprocessor and main parser) are +still covered by this copyright. The main portion is covered by the usual +cc65 license, which reads: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + diff --git a/doc/cl65.sgml b/doc/cl65.sgml new file mode 100644 index 000000000..a574049cc --- /dev/null +++ b/doc/cl65.sgml @@ -0,0 +1,316 @@ +<!doctype linuxdoc system> + +<article> +<title>cl65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>01.08.2000, 27.11.2000, 02.10.2001 + +<abstract> +cl65 is the compile & link utility for cc65, the 6502 C compiler. It was +designed as a smart frontend for the C compiler (cc65), the assembler (ca65), +the object file converter (co65), and the linker (ld65). +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +cl65 is a frontend for cc65, ca65, co65 and ld65. While you may not use the +full power of the tools when calling them through cl65, most features are +available, and the use of cl65 is much simpler. + + +<sect>Basic Usage<p> + +The cl65 compile and link utility may be used to convert, compile, assemble +and link files. While the separate tools do just one step, cl65 knows how to +build object files from C files (by calling the compiler, then the assembler) +and other things. + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: cl65 [options] file [...] +Short options: + -c Compile and assemble but don't link + -d Debug mode + -g Add debug info + -h Help (this text) + -l name Create an assembler listing file + -m name Create a map file + -mm model Set the memory model + -o name Name the output file + -r Enable register variables + -t sys Set the target system + -u sym Force an import of symbol `sym' + -v Verbose mode + -vm Verbose map file + -C name Use linker config file + -Cl Make local variables static + -D sym[=defn] Define a preprocessor symbol + -I dir Set a compiler include directory path + -L path Specify a library search path + -Ln name Create a VICE label file + -O Optimize code + -Oi Optimize code, inline functions + -Or Optimize code, honour the register keyword + -Os Optimize code, inline known C funtions + -S Compile but don't assemble and link + -T Include source as comment + -V Print the version number + -W name[,...] Supress compiler warnings + -Wa options Pass options to the assembler + -Wl options Pass options to the linker + +Long options: + --add-source Include source as comment + --asm-args options Pass options to the assembler + --asm-define sym[=v] Define an assembler symbol + --asm-include-dir dir Set an assembler include directory + --bin-include-dir dir Set an assembler binary include directory + --bss-label name Define and export a BSS segment label + --bss-name seg Set the name of the BSS segment + --cc-args options Pass options to the compiler + --cfg-path path Specify a config file search path + --check-stack Generate stack overflow checks + --code-label name Define and export a CODE segment label + --code-name seg Set the name of the CODE segment + --codesize x Accept larger code by factor x + --config name Use linker config file + --cpu type Set cpu type + --create-dep name Create a make dependency file + --create-full-dep name Create a full make dependency file + --data-label name Define and export a DATA segment label + --data-name seg Set the name of the DATA segment + --debug Debug mode + --debug-info Add debug info + --feature name Set an emulation feature + --force-import sym Force an import of symbol `sym' + --forget-inc-paths Forget include search paths (compiler) + --help Help (this text) + --include-dir dir Set a compiler include directory path + --ld-args options Pass options to the linker + --lib file Link this library + --lib-path path Specify a library search path + --list-targets List all available targets + --listing name Create an assembler listing file + --list-bytes n Number of bytes per assembler listing line + --mapfile name Create a map file + --memory-model model Set the memory model + --module Link as a module + --module-id id Specify a module id for the linker + --o65-model model Override the o65 model + --obj file Link this object file + --obj-path path Specify an object file search path + --register-space b Set space available for register variables + --register-vars Enable register variables + --rodata-name seg Set the name of the RODATA segment + --signed-chars Default characters are signed + --standard std Language standard (c89, c99, cc65) + --start-addr addr Set the default start address + --static-locals Make local variables static + --target sys Set the target system + --version Print the version number + --verbose Verbose mode + --zeropage-label name Define and export a ZEROPAGE segment label + --zeropage-name seg Set the name of the ZEROPAGE segment +--------------------------------------------------------------------------- +</verb></tscreen> + +Most of the options have the same meaning than the corresponding compiler, +assembler or linker option. See the documentation for these tools for an +explanation. If an option is available for more than one of the tools, it +is set for all tools, where it is available. One example for this is <tt/-v/: +The compiler, the assembler and the linker are all called with the <tt/-v/ +switch. + +There are a few remaining options that control the behaviour of cl65: + +<descrip> + + <tag><tt>-S</tt></tag> + + This option forces cl65 to stop after the assembly step. This means that + C files are translated into assembler files, but nothing more is done. + Assembler files, object files and libraries given on the command line + are ignored. + + + <tag><tt>-c</tt></tag> + + This options forces cl65 to stop after the assembly step. This means + that C and assembler files given on the command line are translated into + object files, but there is no link step, and object files and libraries + given on the command line are ignored. + + + <tag><tt>-o name</tt></tag> + + The -o option is used for the target name in the final step. This causes + problems, if the linker will not be called, and there are several input + files on the command line. In this case, the name given with -o will be + used for all of them, which makes the option pretty useless. You + shouldn't use -o when more than one output file is created. + + + <tag><tt>-t sys, --target sys</tt></tag> + + The default for this option is different from the compiler and linker in the + case that the option is missing: While the other tools (compiler, assembler + and linker) will use the "none" system settings by default, cl65 will use + the C64 as a target system by default. This was chosen since most people + seem to use cc65 to develop for the C64. + + <tag><tt>-Wa options, --asm-args options</tt></tag> + + Pass options directly to the assembler. This may be used to pass options + that aren't directly supported by cl65. Several options may be separated by + commas, the commas are replaced by spaces when passing them to the + assembler. Beware: Passing arguments directly to the assembler may interfere + with some of the defaults, because cl65 doesn't parse the options passed. So + if cl65 supports an option by itself, do not pass this option to the + assembler by means of the <tt/-Wa/ switch. + + <tag><tt>-Wc options, --cc-args options</tt></tag> + + Pass options directly to the compiler. This may be used to pass options + that aren't directly supported by cl65. Several options may be separated by + commas, the commas are replaced by spaces when passing them to the + compiler. Beware: Passing arguments directly to the compiler may interfere + with some of the defaults, because cl65 doesn't parse the options passed. So + if cl65 supports an option by itself, do not pass this option to the + compiler by means of the <tt/-Wc/ switch. + + <tag><tt>-Wl options, --ld-args options</tt></tag> + + Pass options directly to the linker. This may be used to pass options that + aren't directly supported by cl65. Several options may be separated by + commas, the commas are replaced by spaces when passing them to the linker. + Beware: Passing arguments directly to the linker may interfere with some of + the defaults, because cl65 doesn't parse the options passed. So if cl65 + supports an option by itself, do not pass this option to the linker by means + of the <tt/-Wl/ switch. + +</descrip> + + + +<sect>More usage<p> + +Since cl65 was created to simplify the use of the cc65 development +package, it tries to be smart about several things. + +<itemize> + +<item> If you don't give a target system on the command line, cl65 + defaults to the C64. + +<item> When linking, cl65 will supply the names of the startup file and + library for the target system to the linker, so you don't have to do + that. + +<item> If the final step is the linker, and the name of the output file was + not explicitly given, cl65 will use the name of the first input file + without the extension, provided that the name of this file has an + extension. So you don't need to name the executable name in most + cases, just give the name of your "main" file as first input file. +</itemize> + +The command line is parsed from left to right, and the actual processing tool +(compiler, assembler, ...) is invoked whenever a file name is encountered. +This means that only the options to the left of a file name are in effect when +this file is processed. It does also mean that you're able to specify +different options for different files on the command line. As an example. + +<tscreen><verb> + cl65 -Oirs main.c -O -g module.c +</verb></tscreen> + +translates main.c with full optimization and module.c with less optimization +and debug info enabled. + +The type of an input file is derived from its extension: + +<itemize> +<item>C files: <tt/.c/ +<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/ +<item>Object files: <tt/.o/ <tt/.obj/ +<item>Libraries: <tt/.a/, <tt/.lib/ +<item>GEOS resource files: <tt/.grc/ +<item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/ +</itemize> + +Please note that the program cannot handle input files with unknown file +extensions. + + +<sect>Examples<p> + +The morse trainer software, which consists of one C file (morse.c) and one +assembler file (irq.s) will need the following separate steps to compile +into an executable named morse: + +<tscreen><verb> + cc65 -g -Oi -t c64 morse.c + ca65 -g morse.s + ca65 -g irq.s + ld65 -o morse -t c64 c64.o morse.o irq.o c64.lib +</verb></tscreen> + +When using cl65, this is simplified to + +<tscreen><verb> + cl65 -g -Oi morse.c irq.s +</verb></tscreen> + +As a general rule, you may use cl65 instead of cc65 at most times, +especially in makefiles to build object files directly from C files. Use + +<tscreen><verb> + .c.o: + cl65 -g -Oi $< +</verb></tscreen> + +to do this. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the utility, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +cl65 (and all cc65 binutils) are (C) Copyright 1998-2004 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + diff --git a/doc/co65.sgml b/doc/co65.sgml new file mode 100644 index 000000000..126ed56fd --- /dev/null +++ b/doc/co65.sgml @@ -0,0 +1,353 @@ +<!doctype linuxdoc system> + +<article> +<title>co65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>12.02.2003 + +<abstract> +co65 is an object file conversion utility. It converts o65 object files into +the native object file format used by the cc65 tool chain. Since o65 is the +file format used by cc65 for loadable drivers, the co65 utility allows (among +other things) to link drivers statically to the generated executables instead +of loading them from disk. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + + +<sect>Overview<p> + +co65 is an object file conversion utility. It converts o65 object files into +assembler files, which may be translated by ca65 to generate object files in +the native object file format used by the cc65 tool chain. + +Since loadable drivers used by the library that comes with cc65 use the o65 +relocatable object code format, using the co65 utility allows to link these +drivers statically. This enables the use of these drivers without loading +additional files from a disk or other secondary storage. + +Another use would be to link object files generated by other development tools +to projects using the cc65 tool chain, but this has not been tested until now, +since such tools are currently rare. + + + +<sect>Usage<p> + +The co65 utility converts one o65 file per run into one assembler files in +ca65 format. The utility tries to autodetect the type of the o65 input file +using the operating system identifier contained in the o65 option list. + + +<sect1>Command line option overview<p> + +The converter may be called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: co65 [options] file +Short options: + -V Print the version number + -g Add debug info to object file + -h Help (this text) + -m model Override the o65 model + -n Don't generate an output file + -o name Name the output file + -v Increase verbosity + +Long options: + --bss-label name Define and export a BSS segment label + --bss-name seg Set the name of the BSS segment + --code-label name Define and export a CODE segment label + --code-name seg Set the name of the CODE segment + --data-label name Define and export a DATA segment label + --data-name seg Set the name of the DATA segment + --debug-info Add debug info to object file + --help Help (this text) + --no-output Don't generate an output file + --o65-model model Override the o65 model + --verbose Increase verbosity + --version Print the version number + --zeropage-label name Define and export a ZEROPAGE segment label + --zeropage-name seg Set the name of the ZEROPAGE segment +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <tag><tt>--bss-label name</tt></tag> + + Set the label used to mark the start of the bss segment. When this option is + given, the label is also exported and may be accessed from other code. When + accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the bss segment, there's no need to + use this option. + + + <tag><tt>--bss-name seg</tt></tag> + + Set the name of the bss segment. The default name is "BSS" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>--code-label name</tt></tag> + + Set the label used to mark the start of the code segment. When this option + is given, the label is also exported and may be accessed from other code. + When accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the code segment, there's no need to + use this option. + + + <tag><tt>--code-name seg</tt></tag> + + Set the name of the code segment. The default name is "CODE" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>--data-label name</tt></tag> + + Set the label used to mark the start of the data segment. When this option + is given, the label is also exported and may be accessed from other code. + When accessing such a label from C code, be sure to include the leading + underscore. If you don't need to access the data segment, there's no need to + use this option. + + + <tag><tt>--data-name seg</tt></tag> + + Set the name of the data segment. The default name is "DATA" which is + compatible with the standard ld65 linker configurations. + + + <tag><tt>-d, --debug</tt></tag> + + Enables debug mode, something that should not be needed for mere mortals. + Currently the converter does only accept cc65 loadable modules generated by + ld65 when not in debug mode. Please note that correct conversion has never + been tested for o65 files from other sources, so be careful when using + <tt/-d/. + + + <tag><tt>-g, --debug-info</tt></tag> + + This will cause the converter to insert a <tt/.DEBUGINFO/ command into the + generated assembler code. This will cause the assembler to include all + symbols in a special section in the object file. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <tag><tt>-m model, --o65-model model</tt></tag> + + Set an o65 model. This option changes the way, output is generated for the + given o65 file. For example, cc65 loadable drivers have a zero page segment, + but this segment must not be defined in the file itself, because the + standard module loader will overlay it with the zeropage space used by the + application that loads this module. So instead of allocating space in the + zero page segment, the converter will reference the start of the zero page + area used by the application. + + Currently, the following models are defined: + + <itemize> + <item>lunix + <item>os/a65 + <item>cc65-module + </itemize> + + The default is to autodetect the model to use from the input file, so + there's rarely a need to use this option. + + + <tag><tt>-n, --no-output</tt></tag> + + Don't do the actual conversion, just read in the o65 file checking for + problems. This option may be used in conjunction with <tt/--verbose/ to + view some information about the input file. + + + <tag><tt>-o name</tt></tag> + + Specify the name of the output file. If you don't specify a name, the + name of the o65 input file is used, with the extension replaced by ".s". + + + <tag><tt>-v, --verbose</tt></tag> + + Using this option, the converter will be somewhat more verbose and print + some information about the o65 input file (among other things). You may use + this option together with <tt/--no-output/ to just get the o65 info. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the compiler. When submitting a bug report, + please include the operating system you're using, and the compiler + version. + + + <tag><tt>--zeropage-label name</tt></tag> + + Set the label used to mark the start of the zeropage segment. When this + option is given, the label is also exported and may be accessed from other + code. When accessing such a label from C code, be sure to include the + leading underscore. If you don't need to access the zeropage segment, + there's no need to use this option. + + + <tag><tt>--zeropage-name seg</tt></tag> + + Set the name of the zeropage segment. The default name is "ZEROPAGE" which is + compatible with the standard ld65 linker configurations. + +</descrip> + + +<sect>Input and output<p> + +The converter will accept one o65 file per invocation and create a file with +the same base name, but with the extension replaced by ".s". The output +file contains assembler code suitable for the use with the ca65 macro +assembler. + + +<sect>Converting loadable drivers<p> + +<sect1>Differences between static linking and runtime loading<p> + +One main use of the utility is conversion of loadable drivers, so they may be +linked statically to an application. Statically linking will cause a few +things to be different from runtime loading: + +<itemize> + +<item> Without changing the segment names, all segments take the default + names used by the standard linker configurations. This means that the + driver code is no longer contingous in memory, instead the code + segment is placed somewhere in between all other code segments, the + data segment is placed with all other data segments and so on. If the + driver doesn't do strange things this shouldn't be a problem. + +<item> With statically linked code, data and bss segments will get intialized + once (when the application is loaded), while a loadable driver will + get its initialization each time the driver is loaded into memory + (which may be more than once in the lifetime of a program). It depends + on the driver if this is a problem. Currently, most drivers supplied + with cc65 behave correctly when linked statically. + +</itemize> + + +<sect1>Additional requirements<p> + +All loadable drivers used by cc65 have a header and a jump table at the start +of the code segment. The header is needed to detect the driver (it may also +contain some data that is necessary to access the driver). The jump table is +used to access the functions in the driver code. + +When loading a driver at runtime, the load address of the driver is also the +address of the code segment, so the locations of the header and jump table are +known. However, when linking the driver statically, it is up to the programmer +to provide this information to the driver API. + +For this purpose, it is necessary to define a code segment label that can be +accessed from the outside later. Please note that the converter does currently +<em/not/ create such a label without being ordered to do so, even if the input +file is a cc65 module. + +To create such a label, use the <tt/--code-label/ option when calling the +converter. Be sure to begin the label with a leading underscore when accessing +it from C code. In your code, define an arbitrary variable with this name. Use +the address of this variable as the address of the code segment of the driver. +Be sure to never modify the variable which is in reality the start of your +driver! + + +<sect1>Example - Convert and link a graphics driver<p> + +As an example, here are some instructions to convert and use the c64-hi.tgi +graphics driver: + +First, convert the driver, generating a label named "_c64_hi" for the code +segment. Use the assembler to generate an object file from the assembler +output. + + <tscreen><verb> + co65 --code-label _c64_hi c64-hi.tgi + ca65 c64-hi.s + </verb></tscreen> + +Next, change your C code to declare a variable that is actually the address +of the driver: + + <tscreen><verb> + extern void c64_hi[]; + </verb></tscreen> + +Instead of loading and unloading the driver, change the code to install and +uninstall the driver, which will be already in memory after linking: + + <tscreen><verb> + /* Install the driver */ + tgi_install (c64_hi); + + ... + + /* Uninstall the driver */ + tgi_uninstall (); + </verb></tscreen> + +Don't forget to link the driver object file to your application, otherwise you +will get an "undefined external" error for the _c64_hi symbol. + + + + +<sect>Bugs/Feedback<p> + +If you have problems using the converter, if you find any bugs, or if you're +doing something interesting with the code, I would be glad to hear from you. +Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +co65 is (C) Copyright 2003 Ullrich von Bassewitz. For usage of the binaries +and/or sources the following conditions apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + diff --git a/doc/coding.sgml b/doc/coding.sgml new file mode 100644 index 000000000..1aa454f12 --- /dev/null +++ b/doc/coding.sgml @@ -0,0 +1,308 @@ +<!doctype linuxdoc system> + +<article> +<title>cc65 coding hints +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2000-12-03, 2009-09-01 + +<abstract> +How to generate the most effective code with cc65. +</abstract> + + + +<sect>Use prototypes<p> + +This will not only help to find errors between separate modules, it will also +generate better code, since the compiler must not assume that a variable sized +parameter list is in place and must not pass the argument count to the called +function. This will lead to shorter and faster code. + + + +<sect>Don't declare auto variables in nested function blocks<p> + +Variable declarations in nested blocks are usually a good thing. But with +cc65, there is a drawback: Since the compiler generates code in one pass, it +must create the variables on the stack each time the block is entered and +destroy them when the block is left. This causes a speed penalty and larger +code. + + + +<sect>Remember that the compiler does no high level optimizations<p> + +The compiler needs hints from you about the code to generate. It will try to +optimize the generated code, but follow the outline you gave in your C +program. So for example, when accessing indexed data structures, get a pointer +to the element and use this pointer instead of calculating the index again and +again. If you want to have your loops unrolled, or loop invariant code moved +outside the loop, you have to do that yourself. + + + +<sect>Longs are slow!<p> + +While long support is necessary for some things, it's really, really slow on +the 6502. Remember that any long variable will use 4 bytes of memory, and any +operation works on double the data compared to an int. + + + +<sect>Use unsigned types wherever possible<p> + +The 6502 CPU has no opcodes to handle signed values greater than 8 bit. So +sign extension, test of signedness etc. has to be done with extra code. As a +consequence, the code to handle signed operations is usually a bit larger and +slower than the same code for unsigned types. + + + +<sect>Use chars instead of ints if possible<p> + +While in arithmetic operations, chars are immidiately promoted to ints, they +are passed as chars in parameter lists and are accessed as chars in variables. +The code generated is usually not much smaller, but it is faster, since +accessing chars is faster. For several operations, the generated code may be +better if intermediate results that are known not to be larger than 8 bit are +casted to chars. + +You should especially use unsigned chars for loop control variables if the +loop is known not to execute more than 255 times. + + + +<sect>Make the size of your array elements one of 1, 2, 4, 8<p> + +When indexing into an array, the compiler has to calculate the byte offset +into the array, which is the index multiplied by the size of one element. When +doing the multiplication, the compiler will do a strength reduction, that is, +replace the multiplication by a shift if possible. For the values 2, 4 and 8, +there are even more specialized subroutines available. So, array access is +fastest when using one of these sizes. + + + +<sect>Expressions are evaluated from left to right<p> + +Since cc65 is not building an explicit expression tree when parsing an +expression, constant subexpressions may not be detected and optimized properly +if you don't help. Look at this example: + +<tscreen><verb> + #define OFFS 4 + int i; + i = i + OFFS + 3; +</verb></tscreen> + +The expression is parsed from left to right, that means, the compiler sees 'i', +and puts it contents into the secondary register. Next is OFFS, which is +constant. The compiler emits code to add a constant to the secondary register. +Same thing again for the constant 3. So the code produced contains a fetch +of 'i', two additions of constants, and a store (into 'i'). Unfortunately, the +compiler does not see, that "OFFS + 3" is a constant for itself, since it does +its evaluation from left to right. There are some ways to help the compiler +to recognize expression like this: + +<enum> + +<item>Write "i = OFFS + 3 + i;". Since the first and second operand are +constant, the compiler will evaluate them at compile time reducing the code to +a fetch, one addition (secondary + constant) and one store. + +<item>Write "i = i + (OFFS + 3)". When seeing the opening parenthesis, the +compiler will start a new expression evaluation for the stuff in the braces, +and since all operands in the subexpression are constant, it will detect this +and reduce the code to one fetch, one addition and one store. + +</enum> + + +<sect>Use the preincrement and predecrement operators<p> + +The compiler is not always smart enough to figure out, if the rvalue of an +increment is used or not. So it has to save and restore that value when +producing code for the postincrement and postdecrement operators, even if this +value is never used. To avoid the additional overhead, use the preincrement +and predecrement operators if you don't need the resulting value. That means, +use + +<tscreen><verb> + ... + ++i; + ... +</verb></tscreen> + + instead of + +<tscreen><verb> + ... + i++; + ... +</verb></tscreen> + + + +<sect>Use constants to access absolute memory locations<p> + +The compiler produces optimized code, if the value of a pointer is a constant. +So, to access direct memory locations, use + +<tscreen><verb> + #define VDC_STATUS 0xD601 + *(char*)VDC_STATUS = 0x01; +</verb></tscreen> + +That will be translated to + +<tscreen><verb> + lda #$01 + sta $D601 +</verb></tscreen> + +The constant value detection works also for struct pointers and arrays, if the +subscript is a constant. So + +<tscreen><verb> + #define VDC ((unsigned char*)0xD600) + #define STATUS 0x01 + VDC[STATUS] = 0x01; +</verb></tscreen> + +will also work. + +If you first load the constant into a variable and use that variable to access +an absolute memory location, the generated code will be much slower, since the +compiler does not know anything about the contents of the variable. + + + +<sect>Use initialized local variables<p> + +Initialization of local variables when declaring them gives shorter and faster +code. So, use + +<tscreen><verb> + int i = 1; +</verb></tscreen> + +instead of + +<tscreen><verb> + int i; + i = 1; +</verb></tscreen> + +But beware: To maximize your savings, don't mix uninitialized and initialized +variables. Create one block of initialized variables and one of uniniitalized +ones. The reason for this is, that the compiler will sum up the space needed +for uninitialized variables as long as possible, and then allocate the space +once for all these variables. If you mix uninitialized and initialized +variables, you force the compiler to allocate space for the uninitialized +variables each time, it parses an initialized one. So do this: + +<tscreen><verb> + int i, j; + int a = 3; + int b = 0; +</verb></tscreen> + +instead of + +<tscreen><verb> + int i; + int a = 3; + int j; + int b = 0; +</verb></tscreen> + +The latter will work, but will create larger and slower code. + + + +<sect>Use the array operator [] even for pointers<p> + +When addressing an array via a pointer, don't use the plus and dereference +operators, but the array operator. This will generate better code in some +common cases. + +Don't use + +<tscreen><verb> + char* a; + char b, c; + char b = *(a + c); +</verb></tscreen> + +Use + +<tscreen><verb> + char* a; + char b, c; + char b = a[c]; +</verb></tscreen> + +instead. + + + +<sect>Use register variables with care<p> + +Register variables may give faster and shorter code, but they do also have an +overhead. Register variables are actually zero page locations, so using them +saves roughly one cycle per access. The calling routine may also use register +variables, so the old values have to be saved on function entry and restored +on exit. Saving an d restoring has an overhead of about 70 cycles per 2 byte +variable. It is easy to see, that - apart from the additional code that is +needed to save and restore the values - you need to make heavy use of a +variable to justify the overhead. + +As a general rule: Use register variables only for pointers that are +dereferenced several times in your function, or for heavily used induction +variables in a loop (with several 100 accesses). + +When declaring register variables, try to keep them together, because this +will allow the compiler to save and restore the old values in one chunk, and +not in several. + +And remember: Register variables must be enabled with <tt/-r/ or <tt/-Or/. + + + +<sect>Decimal constants greater than 0x7FFF are actually long ints<p> + +The language rules for constant numeric values specify that decimal constants +without a type suffix that are not in integer range must be of type long int +or unsigned long int. So a simple constant like 40000 is of type long int! +This is often unexpected and may cause an expression to be evaluated with 32 +bits. While in many cases the compiler takes care about it, in some places it +can't. So be careful when you get a warning like + +<tscreen><verb> + test.c(7): Warning: Constant is long +</verb></tscreen> + +Use the <tt/U/, <tt/L/ or <tt/UL/ suffixes to tell the compiler the desired +type of a numeric constant. + + + +<sect>Access to parameters in variadic functions is expensive<p> + +Since cc65 has the "wrong" calling order, the location of the fixed parameters +in a variadic function (a function with a variable parameter list) depends on +the number and size of variable arguments passed. Since this number and size +is unknown at compile time, the compiler will generate code to calculate the +location on the stack when needed. + +Because of this additional code, accessing the fixed parameters in a variadic +function is much more expensive than access to parameters in a "normal" +function. Unfortunately, this additional code is also invisible to the +programmer, so it is easy to forget. + +As a rule of thumb, if you access such a parameter more than once, you should +think about copying it into a normal variable and using this variable instead. + + +</article> + diff --git a/doc/customizing.sgml b/doc/customizing.sgml new file mode 100644 index 000000000..23cf8c5e8 --- /dev/null +++ b/doc/customizing.sgml @@ -0,0 +1,730 @@ +<!doctype linuxdoc system> + +<article> +<title>Defining a Custom cc65 Target +<author>Bruce Reidenbach +<date>2010-02-22 + +<abstract> +This section provides step-by-step instructions on how to use the cc65 +toolset for a custom hardware platform (a target system not currently +supported by the cc65 library set). +</abstract> + +<!-- Table of contents --> + +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +The cc65 toolset provides a set of pre-defined libraries that allow the +user to target the executable image to a variety of hardware platforms. +In addition, the user can create a customized environment so that the +executable can be targeted to a custom platform. The following +instructions provide step-by-step instructions on how to customize the +toolset for a target that is not supported by the standard cc65 +installation. + +The platform used in this example is a Xilinx Field Programmable Gate +Array (FPGA) with an embedded 65C02 core. The processor core supports +the additional opcodes/addressing modes of the 65SC02, along with the +STP and WAI instructions. These instructions will create a set of files +to create a custom target, named SBC, for <bf>S</bf>ingle <bf>B</bf>oard +<bf>C</bf>omputer. + +<sect>System Memory Map Definition<p> + +The targeted system uses block RAM contained on the XILINX FPGA for the +system memory (both RAM and ROM). The block RAMs are available in +various aspect ratios, and they will be used in this system as 2K*8 +devices. There will be two RAMs used for data storage, starting at +location $0000 and growing upwards. There will be one ROM (realized as +initialized RAM) used code storage, starting at location $FFFF and +growing downwards. + +The cc65 toolset requires a memory configuration file to define the +memory that is available to the cc65 run-time environment, which is +defined as follows: + +<tscreen><code> +MEMORY { + ZP: start = $0, size = $100, type = rw, define = yes; + RAM: start = $200, size = $0E00, define = yes; + ROM: start = $F800, size = $0800, file = %O; +} +</code></tscreen> + +ZP defines the available zero page locations, which in this case starts +at $0 and has a length of $100. Keep in mind that certain systems may +require access to some zero page locations, so the starting address may +need to be adjusted accordingly to prevent cc65 from attempting to reuse +those locations. Also, at a minimum, the cc65 run-time environment uses +26 zero page locations, so the smallest zero page size that can be +specified is $1A. The usable RAM memory area begins after the 6502 +stack storage in page 1, so it is defined as starting at location $200 +and filling the remaining 4K of space (4096 - 2 * +256 = 3584 = $0E00). The 2K of ROM space begins at +address $F800 and goes to $FFFF (size = $0800). + +Next, the memory segments within the memory devices need to be defined. +A standard segment definition is used, with one notable exception. The +interrupt and reset vector locations need to be defined at locations +$FFFA through $FFFF. A special segment named VECTORS is defined that +resides at these locations. Later, the interrupt vector map will be +created and placed in the VECTORS segment, and the linker will put these +vectors at the proper memory locations. The segment definition is: + +<tscreen><code> +SEGMENTS { + ZEROPAGE: load = ZP, type = zp, define = yes; + DATA: load = ROM, type = rw, define = yes, run = RAM; + BSS: load = RAM, type = bss, define = yes; + HEAP: load = RAM, type = bss, optional = yes; + STARTUP: load = ROM, type = ro; + INIT: load = ROM, type = ro, optional = yes; + CODE: load = ROM, type = ro; + RODATA: load = ROM, type = ro; + VECTORS: load = ROM, type = ro, start = $FFFA; +} +</code></tscreen> + +The meaning of each of these segments is as follows. + +<p><tt> ZEROPAGE: </tt>Data in page 0, defined by ZP as starting at $0 with length $100 +<p><tt> DATA: </tt>Initialized data that can be modified by the program, stored in RAM +<p><tt> BSS: </tt>Uninitialized data stored in RAM (used for variable storage) +<p><tt> HEAP: </tt>Uninitialized C-level heap storage in RAM, optional +<p><tt> STARTUP: </tt>The program initialization code, stored in ROM +<p><tt> INIT: </tt>The code needed to initialize the system, stored in ROM +<p><tt> CODE: </tt>The program code, stored in ROM +<p><tt> RODATA: </tt>Initialized data that cannot be modified by the program, stored in ROM +<p><tt> VECTORS: </tt>The interrupt vector table, stored in ROM at location $FFFA + +A note about initialized data: any variables that require an initial +value, such as external (global) variables, require that the initial +values be stored in the ROM code image. However, variables stored in +ROM cannot change; therefore the data must be moved into variables that +are located in RAM. Specifying <tt>run = RAM</tt> as part of +the DATA segment definition will indicate that those variables will +require their initialization value to be copied via a call to the +<tt>copydata</tt> routine in the startup assembly code. In addition, +there are system level variables that will need to be initialized as +well, especially if the heap segment is used via a C-level call to +<tt>malloc ()</tt>. + +The final section of the definition file contains the data constructors +and destructors used for system startup. In addition, if the heap is +used, the maximum C-level stack size needs to be defined in order for +the system to be able to reliably allocate blocks of memory. The stack +size selection must be greater than the maximum amount of storage +required to run the program, keeping in mind that the C-level subroutine +call stack and all local variables are stored in this stack. The +<tt>FEATURES</tt> section defines the required constructor/destructor +attributes and the <tt>SYMBOLS</tt> section defines the stack size. The +constructors will be run via a call to <tt>initlib</tt> in the startup +assembly code and the destructors will be run via an assembly language +call to <tt>donelib</tt> during program termination. + +<tscreen><code> +FEATURES { + CONDES: segment = STARTUP, + type = constructor, + label = __CONSTRUCTOR_TABLE__, + count = __CONSTRUCTOR_COUNT__; + CONDES: segment = STARTUP, + type = destructor, + label = __DESTRUCTOR_TABLE__, + count = __DESTRUCTOR_COUNT__; +} + +SYMBOLS { + # Define the stack size for the application + __STACKSIZE__: value = $0200, weak = yes; +} +</code></tscreen> + +These definitions are placed in a file named "sbc.cfg" +and are referred to during the ld65 linker stage. + +<sect>Startup Code Definition<p> + +In the cc65 toolset, a startup routine must be defined that is executed +when the CPU is reset. This startup code is marked with the STARTUP +segment name, which was defined in the system configuration file as +being in read only memory. The standard convention used in the +predefined libraries is that this code is resident in the crt0 module. +For this custom system, all that needs to be done is to perform a little +bit of 6502 housekeeping, set up the C-level stack pointer, initialize +the memory storage, and call the C-level routine <tt>main ()</tt>. +The following code was used for the crt0 module, defined in the file +"crt0.s": + +<tscreen><code> +; --------------------------------------------------------------------------- +; crt0.s +; --------------------------------------------------------------------------- +; +; Startup code for cc65 (Single Board Computer version) + +.export _init, _exit +.import _main + +.export __STARTUP__ : absolute = 1 ; Mark as startup +.import __RAM_START__, __RAM_SIZE__ ; Linker generated + +.import copydata, zerobss, initlib, donelib + +.include "zeropage.inc" + +; --------------------------------------------------------------------------- +; Place the startup code in a special segment + +.segment "STARTUP" + +; --------------------------------------------------------------------------- +; A little light 6502 housekeeping + +_init: LDX #$FF ; Initialize stack pointer to $01FF + TXS + CLD ; Clear decimal mode + +; --------------------------------------------------------------------------- +; Set cc65 argument stack pointer + + LDA #<(__RAM_START__ + __RAM_SIZE__) + STA sp + LDA #>(__RAM_START__ + __RAM_SIZE__) + STA sp+1 + +; --------------------------------------------------------------------------- +; Initialize memory storage + + JSR zerobss ; Clear BSS segment + JSR copydata ; Initialize DATA segment + JSR initlib ; Run constructors + +; --------------------------------------------------------------------------- +; Call main() + + JSR _main + +; --------------------------------------------------------------------------- +; Back from main (this is also the _exit entry): force a software break + +_exit: JSR donelib ; Run destructors + BRK +</code></tscreen> + +The following discussion explains the purpose of several important +assembler level directives in this file. + +<tscreen><verb> +.export _init, _exit +</verb></tscreen> + +This line instructs the assembler that the symbols <tt>_init</tt> and +<tt>_exit</tt> are to be accessible from other modules. In this +example, <tt>_init</tt> is the location that the CPU should jump to when +reset, and <tt>_exit</tt> is the location that will be called when the +program is finished. + +<tscreen><verb> +.import _main +</verb></tscreen> + +This line instructs the assembler to import the symbol <tt>_main</tt> +from another module. cc65 names all C-level routines as +{underscore}{name} in assembler, thus the <tt>main ()</tt> routine +in C is named <tt>_main</tt> in the assembler. This is how the startup +code will link to the C-level code. + +<tscreen><verb> +.export __STARTUP__ : absolute = 1 ; Mark as startup +</verb></tscreen> + +This line marks this code as startup code (code that is executed when +the processor is reset), which will then be automatically linked into +the executable code. + +<tscreen><verb> +.import __RAM_START__, __RAM_SIZE__ ; Linker generated +</verb></tscreen> + +This line imports the RAM starting address and RAM size constants, which +are used to initialize the cc65 C-level argument stack pointer. + +<tscreen><verb> +.segment "STARTUP" +</verb></tscreen> + +This line instructs the assembler that the code is to be placed in the +STARTUP segment of memory. + +<tscreen><verb> + JSR zerobss ; Clear BSS segment + JSR copydata ; Initialize DATA segment + JSR initlib ; Run constructors +</verb></tscreen> + +These three lines initialize the external (global) and system +variables. The first line sets the BSS segment -- the memory locations +used for external variables -- to 0. The second line copies the +initialization value stored in ROM to the RAM locations used for +initialized external variables. The last line runs the constructors +that are used to initialize the system run-time variables. + +<tscreen><verb> + JSR _main +</verb></tscreen> + +This is the actual call to the C-level <tt>main ()</tt> routine, +which is called after the startup code completes. + +<tscreen><verb> +_exit: JSR donelib ; Run destructors + BRK +</verb></tscreen> + +This is the code that will be executed when <tt>main ()</tt> +terminates. The first thing that must be done is run the destructors +via a call to <tt>donelib</tt>. Then the program can terminate. In +this example, the program is expected to run forever. Therefore, there +needs to be a way of indicating when something has gone wrong and the +system needs to be shut down, requiring a restart only by a hard reset. +The BRK instruction will be used to indicate a software fault. This is +advantageous because cc65 uses the BRK instruction as the fill byte in +the final binary code. In addition, the hardware has been designed to +force the data lines to $00 for all illegal memory accesses, thereby +also forcing a BRK instruction into the CPU. + +<sect>Custom Run-Time Library Creation<p> + +The next step in customizing the cc65 toolset is creating a run-time +library for the targeted hardware. The easiest way to do this is to +modify a standard library from the cc65 distribution. In this example, +there is no console I/O, mouse, joystick, etc. in the system, so it is +most appropriate to use the simplest library as the base, which is for +the Watara Supervision and is named "supervision.lib" in the +lib directory of the distribution. + +The only modification required is to replace the <tt>crt0</tt> module in +the supervision.lib library with custom startup code. This is simply +done by first copying the library and giving it a new name, compiling +the startup code with ca65, and finally using the ar65 archiver to +replace the module in the new library. The steps are shown below: + +<tscreen><verb> +$ copy "C:\Program Files\cc65\lib\supervision.lib" sbc.lib +$ ca65 crt0.s +$ ar65 a sbc.lib crt0.o +</verb></tscreen> + +<sect>Interrupt Service Routine Definition<p> + +For this system, the CPU is put into a wait condition prior to allowing +interrupt processing. Therefore, the interrupt service routine is very +simple: return from all valid interrupts. However, as mentioned +before, the BRK instruction is used to indicate a software fault, which +will call the same interrupt service routine as the maskable interrupt +signal IRQ. The interrupt service routine must be able to tell the +difference between the two, and act appropriately. + +The interrupt service routine shown below includes code to detect when a +BRK instruction has occurred and stops the CPU from further processing. +The interrupt service routine is in a file named +"interrupt.s". + +<tscreen><code> +; --------------------------------------------------------------------------- +; interrupt.s +; --------------------------------------------------------------------------- +; +; Interrupt handler. +; +; Checks for a BRK instruction and returns from all valid interrupts. + +.import _stop +.export _irq_int, _nmi_int + +.segment "CODE" + +.PC02 ; Force 65C02 assembly mode + +; --------------------------------------------------------------------------- +; Non-maskable interrupt (NMI) service routine + +_nmi_int: RTI ; Return from all NMI interrupts + +; --------------------------------------------------------------------------- +; Maskable interrupt (IRQ) service routine + +_irq_int: PHX ; Save X register contents to stack + TSX ; Transfer stack pointer to X + PHA ; Save accumulator contents to stack + INX ; Increment X so it points to the status + INX ; register value saved on the stack + LDA $100,X ; Load status register contents + AND #$10 ; Isolate B status bit + BNE break ; If B = 1, BRK detected + +; --------------------------------------------------------------------------- +; IRQ detected, return + +irq: PLA ; Restore accumulator contents + PLX ; Restore X register contents + RTI ; Return from all IRQ interrupts + +; --------------------------------------------------------------------------- +; BRK detected, stop + +break: JMP _stop ; If BRK is detected, something very bad + ; has happened, so stop running +</code></tscreen> + +The following discussion explains the purpose of several important +assembler level directives in this file. + +<tscreen><verb> +.import _stop +</verb></tscreen> + +This line instructs the assembler to import the symbol <tt>_stop</tt> +from another module. This routine will be called if a BRK instruction +is encountered, signaling a software fault. + +<tscreen><verb> +.export _irq_int, _nmi_int +</verb></tscreen> + +This line instructs the assembler that the symbols <tt>_irq_int</tt> and +<tt>_nmi_int</tt> are to be accessible from other modules. In this +example, the address of these symbols will be placed in the interrupt +vector table. + +<tscreen><verb> +.segment "CODE" +</verb></tscreen> + +This line instructs the assembler that the code is to be placed in the +CODE segment of memory. Note that because there are 65C02 mnemonics in +the assembly code, the assembler is forced to use the 65C02 instruction +set with the <tt>.PC02</tt> directive. + +The final step is to define the interrupt vector memory locations. +Recall that a segment named VECTORS was defined in the memory +configuration file, which started at location $FFFA. The addresses of +the interrupt service routines from "interrupt.s" along with +the address for the initialization code in crt0 are defined in a file +named "vectors.s". Note that these vectors will be placed in +memory in their proper little-endian format as: + +<p><tt> $FFFA - $FFFB:</tt> NMI interrupt vector (low byte, high byte) +<p><tt> $FFFC - $FFFD:</tt> Reset vector (low byte, high byte) +<p><tt> $FFFE - $FFFF:</tt> IRQ/BRK interrupt vector (low byte, high byte) + +using the <tt>.addr</tt> assembler directive. The contents of the file are: + +<tscreen><code> +; --------------------------------------------------------------------------- +; vectors.s +; --------------------------------------------------------------------------- +; +; Defines the interrupt vector table. + +.import _init +.import _nmi_int, _irq_int + +.segment "VECTORS" + +.addr _nmi_int ; NMI vector +.addr _init ; Reset vector +.addr _irq_int ; IRQ/BRK vector +</code></tscreen> + +The cc65 toolset will replace the address symbols defined here with the +actual addresses of the routines during the link process. + +<sect>Adding Custom Instructions<p> + +The cc65 instruction set only supports the WAI (Wait for Interrupt) and +STP (Stop) instructions when used with the 65816 CPU (accessed via the +--cpu command line option of the ca65 macro assembler). The 65C02 core +used in this example supports these two instructions, and in fact the +system benefits from the use of both the WAI and STP instructions. + +In order to use the WAI instruction in this case, a C routine named +"wait" was created that consists of the WAI opcode followed by +a subroutine return. It was convenient in this example to put the IRQ +interrupt enable in this subroutine as well, since interrupts should +only be enabled when the code is in this wait condition. + +For both the WAI and STP instructions, the assembler is +"fooled" into placing those opcodes into memory by inserting a +single byte of data that just happens to be the opcode for those +instructions. The assembly code routines are placed in a file, named +"wait.s", which is shown below: + +<tscreen><code> +; --------------------------------------------------------------------------- +; wait.s +; --------------------------------------------------------------------------- +; +; Wait for interrupt and return + +.export _wait, _stop + +; --------------------------------------------------------------------------- +; Wait for interrupt: Forces the assembler to emit a WAI opcode ($CB) +; --------------------------------------------------------------------------- + +.segment "CODE" + +.proc _wait: near + + CLI ; Enable interrupts +.byte $CB ; Inserts a WAI opcode + RTS ; Return to caller + +.endproc + +; --------------------------------------------------------------------------- +; Stop: Forces the assembler to emit a STP opcode ($DB) +; --------------------------------------------------------------------------- + +.proc _stop: near + +.byte $DB ; Inserts a STP opcode + +.endproc +</code></tscreen> + +The label <tt>_wait</tt>, when exported, can be called by using the +<tt>wait ()</tt> subroutine call in C. The section is marked as +code so that it will be stored in read-only memory, and the procedure is +tagged for 16-bit absolute addressing via the "near" +modifier. Similarly, the <tt>_stop</tt> routine can be called from +within the C-level code via a call to <tt>stop ()</tt>. In +addition, the routine can be called from assembly code by calling +<tt>_stop</tt> (as was done in the interrupt service routine). + +<sect>Hardware Drivers<p> + +Oftentimes, it can be advantageous to create small application helpers +in assembly language to decrease codespace and increase execution speed +of the overall program. An example of this would be the transfer of +characters to a FIFO (<bf>F</bf>irst-<bf>I</bf>n, +<bf>F</bf>irst-<bf>O</bf>ut) storage buffer for transmission over a +serial port. This simple action could be performed by an assembly +language driver which would execute much quicker than coding it in C. +The following discussion outlines a method of interfacing a C program +with an assembly language subroutine. + +The first step in creating the assembly language code for the driver is +to determine how to pass the C arguments to the assembly language +routine. The cc65 toolset allows the user to specify whether the data +is passed to a subroutine via the stack or by the processor registers by +using the <tt>__fastcall__</tt> function declaration (note that there +are two underscore characters in front of and two behind the +<tt>fastcall</tt> declaration). When <tt>__fastcall__</tt> is +specified, the rightmost argument in the function call is passed to the +subroutine using the 6502 registers instead of the stack. Note that if +there is only one argument in the function call, the execution overhead +required by the stack interface routines is completely avoided. + +Without <tt>__fastcall__</tt>, the argument is loaded in the A and X +registers and then pushed onto the stack via a call to <tt>pushax</tt>. +The first thing the subroutine does is retrieve the argument from the +stack via a call to <tt>ldax0sp</tt>, which copies the values into the A +and X. When the subroutine is finished, the values on the stack must be +popped off and discarded via a jump to <tt>incsp2</tt>, which includes +the RTS subroutine return command. This is shown in the following code +sample. + +Calling sequence: + +<tscreen><verb> + lda #<(L0001) ; Load A with the high order byte + ldx #>(L0001) ; Load X with the low order byte + jsr pushax ; Push A and X onto the stack + jsr _foo ; Call foo, i.e., foo (arg) +</verb></tscreen> + +Subroutine code: + +<tscreen><verb> +_foo: jsr ldax0sp ; Retrieve A and X from the stack + sta ptr ; Store A in ptr + stx ptr+1 ; Store X in ptr+1 + ... ; (more subroutine code goes here) + jmp incsp2 ; Pop A and X from the stack (includes return) +</verb></tscreen> + +If <tt>__fastcall__</tt> is specified, the argument is loaded into the A +and X registers as before, but the subroutine is then called +immediately. The subroutine does not need to retrieve the argument +since the value is already available in the A and X registers. +Furthermore, the subroutine can be terminated with an RTS statement +since there is no stack cleanup which needs to be performed. This is +shown in the following code sample. + +Calling sequence: + +<tscreen><verb> + lda #<(L0001) ; Load A with the high order byte + ldx #>(L0001) ; Load X with the low order byte + jsr _foo ; Call foo, i.e., foo (arg) +</verb></tscreen> + +Subroutine code: + +<tscreen><verb> +_foo: sta ptr ; Store A in ptr + stx ptr+1 ; Store X in ptr+1 + ... ; (more subroutine code goes here) + rts ; Return from subroutine +</verb></tscreen> + +The hardware driver in this example writes a string of character data to +a hardware FIFO located at memory location $1000. Each character is +read and is compared to the C string termination value ($00), which will +terminate the loop. All other character data is written to the FIFO. +For convenience, a carriage return/line feed sequence is automatically +appended to the serial stream. The driver defines a local pointer +variable which is stored in the zero page memory space in order to allow +for retrieval of each character in the string via the indirect indexed +addressing mode. + +The assembly language routine is stored in a file names +"rs232_tx.s" and is shown below: + +<tscreen><code> +; --------------------------------------------------------------------------- +; rs232_tx.s +; --------------------------------------------------------------------------- +; +; Write a string to the transmit UART FIFO + +.export _rs232_tx +.exportzp _rs232_data: near + +.define TX_FIFO $1000 ; Transmit FIFO memory location + +.zeropage + +_rs232_data: .res 2, $00 ; Reserve a local zero page pointer + +.segment "CODE" + +.proc _rs232_tx: near + +; --------------------------------------------------------------------------- +; Store pointer to zero page memory and load first character + + sta _rs232_data ; Set zero page pointer to string address + stx _rs232_data+1 ; (pointer passed in via the A/X registers) + ldy #00 ; Initialize Y to 0 + lda (_rs232_data) ; Load first character + +; --------------------------------------------------------------------------- +; Main loop: read data and store to FIFO until \0 is encountered + +loop: sta TX_FIFO ; Loop: Store character in FIFO + iny ; Increment Y index + lda (_rs232_data),y ; Get next character + bne loop ; If character == 0, exit loop + +; --------------------------------------------------------------------------- +; Append CR/LF to output stream and return + + lda #$0D ; Store CR + sta TX_FIFO + lda #$0A ; Store LF + sta TX_FIFO + rts ; Return + +.endproc +</code></tscreen> + +<sect>Hello World! Example<p> + +The following short example demonstrates programming in C using the cc65 +toolset with a custom run-time environment. In this example, a Xilinx +FPGA contains a UART which is connected to a 65c02 processor with FIFO +(<bf>F</bf>irst-<bf>I</bf>n, <bf>F</bf>irst-<bf>O</bf>ut) storage to +buffer the data. The C program will wait for an interrupt generated by +the receive UART and then respond by transmitting the string "Hello +World! " every time a question mark character is received via a +call to the hardware driver <tt>rs232_tx ()</tt>. The driver +prototype uses the <tt>__fastcall__</tt> extension to indicate that the +driver does not use the stack. The FIFO data interface is at address +$1000 and is defined as the symbolic constant <tt>FIFO_DATA</tt>. +Writing to <tt>FIFO_DATA</tt> transfers a byte of data into the transmit +FIFO for subsequent transmission over the serial interface. Reading +from <tt>FIFO_DATA</tt> transfers a byte of previously received data out +of the receive FIFO. The FIFO status data is at address $1001 and is +defined as the symbolic constant <tt>FIFO_STATUS</tt>. For convenience, +the symbolic constants <tt>TX_FIFO_FULL</tt> (which isolates bit 0 of +the register) and <tt>RX_FIFO_EMPTY</tt> (which isolates bit 1 of the +register) have been defined to read the FIFO status. + +The following C code is saved in the file "main.c". As this +example demonstrates, the run-time environment has been set up such that +all of the behind-the-scene work is transparent to the user. + +<tscreen><code> +#define FIFO_DATA (*(unsigned char *) 0x1000) +#define FIFO_STATUS (*(unsigned char *) 0x1001) + +#define TX_FIFO_FULL (FIFO_STATUS & 0x01) +#define RX_FIFO_EMPTY (FIFO_STATUS & 0x02) + +extern void wait (); +extern void __fastcall__ rs232_tx (char *str); + +int main () { + while (1) { // Run forever + wait (); // Wait for an RX FIFO interrupt + + while (RX_FIFO_EMPTY == 0) { // While the RX FIFO is not empty + if (FIFO_DATA == '?') { // Does the RX character = '?' + rs232_tx ("Hello World!"); // Transmit "Hello World!" + } // Discard any other RX characters + } + } + + return (0); // We should never get here! +} +</code></tscreen> + +<sect>Putting It All Together<p> + +The following commands will create a ROM image named "a.out" +that can be used as the initialization data for the Xilinx Block RAM +used for code storage: + +<tscreen><verb> +$ cc65 -t none -O --cpu 65sc02 main.c +$ ca65 --cpu 65sc02 main.s +$ ca65 --cpu 65sc02 rs232_tx.s +$ ca65 --cpu 65sc02 interrupt.s +$ ca65 --cpu 65sc02 vectors.s +$ ca65 --cpu 65sc02 wait.s +$ ld65 -C sbc.cfg -m main.map interrupt.o vectors.o wait.o rs232_tx.o + main.o sbc.lib +</verb></tscreen> + +During the C-level code compilation phase (<tt>cc65</tt>), assumptions +about the target system are disabled via the <tt>-t none</tt> command +line option. During the object module linker phase (<tt>ld65</tt>), the +target customization is enabled via inclusion of the <tt>sbc.lib</tt> +file and the selection of the configuration file via the <tt>-C +sbc.cfg</tt> command line option. + +The 65C02 core used most closely matches the cc65 toolset processor +named 65SC02 (the 65C02 extensions without the bit manipulation +instructions), so all the commands specify the use of that processor via +the <tt>--cpu 65sc02</tt> option. + +</article> diff --git a/doc/da65.sgml b/doc/da65.sgml new file mode 100644 index 000000000..58d031eff --- /dev/null +++ b/doc/da65.sgml @@ -0,0 +1,694 @@ +<!doctype linuxdoc system> + +<article> +<title>da65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-08-08 + +<abstract> +da65 is a 6502/65C02 disassembler that is able to read user supplied +information about its input data for better results. The output is ready for +feeding into ca65, the macro assembler supplied with the cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with +the cc65 C compiler and generates output that is suitable for the ca65 +macro assembler. + +Besides generating output for ca65, one of the design goals was that the user +is able to feed additional information about the code into the disassembler +for improved results. This information may include the location and size of +tables, and their format. + +One nice advantage of this concept is that disassembly of copyrighted binaries +may be handled without problems: One can just pass the information file for +disassembling the binary, so everyone with a legal copy of the binary can +generate a nicely formatted disassembly with readable labels and other +information. + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The assembler accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: da65 [options] [inputfile] +Short options: + -g Add debug info to object file + -h Help (this text) + -i name Specify an info file + -o name Name the output file + -v Increase verbosity + -F Add formfeeds to the output + -S addr Set the start/load address + -V Print the disassembler version + +Long options: + --argument-column n Specify argument start column + --comment-column n Specify comment start column + --comments n Set the comment level for the output + --cpu type Set cpu type + --debug-info Add debug info to object file + --formfeeds Add formfeeds to the output + --help Help (this text) + --hexoffs Use hexadecimal label offsets + --info name Specify an info file + --label-break n Add newline if label exceeds length n + --mnemonic-column n Specify mnemonic start column + --pagelength n Set the page length for the listing + --start-addr addr Set the start/load address + --text-column n Specify text start column + --verbose Increase verbosity + --version Print the disassembler version +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <label id="option--argument-column"> + <tag><tt>--argument-column n</tt></tag> + + Specifies the column where the argument for a mnemonic or pseudo instruction + starts. + + + <label id="option--comment-column"> + <tag><tt>--comment-column n</tt></tag> + + Specifies the column where the comment for an instruction starts. + + + <label id="option--comments"> + <tag><tt>--comments n</tt></tag> + + Set the comment level for the output. Valid arguments are 0..4. Greater + values will increase the level of additional information written to the + output file in form of comments. + + + <label id="option--cpu"> + <tag><tt>--cpu type</tt></tag> + + Set the CPU type. The option takes a parameter, which may be one of + + 6502, 6502x, 65sc02, 65c02, huc6280 + + 6502x is the NMOS 6502 with illegal opcodes. huc6280 is the CPU of the PC + engine. Support for the 65816 is currently not available. + + + <label id="option--formfeeds"> + <tag><tt>-F, --formfeeds</tt></tag> + + Add formfeeds to the generated output. This feature is useful together + with the <tt><ref id="option--pagelength" name="--pagelength"></tt> option. + If <tt/--formfeeds/ is given, a formfeed is added to the output after each + page. + + + <tag><tt>-g, --debug-info</tt></tag> + + This option adds the <tt/.DEBUGINFO/ command to the output file, so the + assembler will generate debug information when reassembling the generated + output. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option--hexoffs"> + <tag><tt>--hexoffs</tt></tag> + + Output label offsets in hexadecimal instead of decimal notation. + + + <label id="option--info"> + <tag><tt>-i name, --info name</tt></tag> + + Specify an info file. The info file contains global options that may + override or replace command line options plus informations about the code + that has to be disassembled. See the separate section <ref id="infofile" + name="Info File Format">. + + + <label id="option-o"> + <tag><tt>-o name</tt></tag> + + Specify a name for an output file. The default is to use <tt/stdout/, so + without this switch or the corresponding <ref id="global-options" + name="global option"> <tt><ref id="OUTPUTNAME" name="OUTPUTNAME"></tt>, + the output will go to the terminal. + + + <label id="option--label-break"> + <tag><tt>--label-break n</tt></tag> + + Adds a newline if the length of a label exceeds the given length. + Note: If the label would run into the code in the mid column, a + linefeed is always inserted regardless of this setting. + + This option overrides the <ref id="global-options" name="global option"> + <tt><ref id="LABELBREAK" name="LABELBREAK"></tt>. + + + <label id="option--mnemonic-column"> + <tag><tt>--mnemonic-column n</tt></tag> + + Specifies the column where a mnemonic or pseudo instrcuction is output. + + + <label id="option--pagelength"> + <tag><tt>--pagelength n</tt></tag> + + Sets the length of a listing page in lines. After this number of lines, a + new page header is generated. If the <tt><ref id="option--formfeeds" + name="--formfeeds"></tt> is also given, a formfeed is inserted before + generating the page header. + + A value of zero for the page length will disable paging of the output. + + + <label id="option--start-addr"> + <tag><tt>-S addr, --start-addr addr</tt></tag> + + Specify the start/load address of the binary code that is going to be + disassembled. The given address is interpreted as an octal value if + preceded with a '0' digit, as a hexadecimal value if preceded + with '0x', '0X', or '$', and as a decimal value in all other cases. If no + start address is specified, $10000 minus the size of the input file is used. + + + <label id="option--text-column"> + <tag><tt>--text-column n</tt></tag> + + Specifies the column where additional text is output. This additional text + consists of the bytes encoded in this line in text representation. + + + <tag><tt>-v, --verbose</tt></tag> + + Increase the disassembler verbosity. Usually only needed for debugging + purposes. You may use this option more than one time for even more + verbose output. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the assembler. If you send any suggestions + or bugfixes, please include the version number. + +</descrip> +<p> + + +<sect>Detailed workings<p> + +<sect1>Supported CPUs<p> + +The default (no CPU given on the command line or in the <tt/GLOBAL/ section of +the info file) is the 6502 CPU. The disassembler knows all "official" opcodes +for this CPU. Invalid opcodes are translated into <tt/.byte/ commands. + +With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the +disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The +latter understands the same opcodes as the former, plus 16 additional bit +manipulation and bit test-and-branch commands. + +While there is some code for the 65816 in the sources, it is currently +unsupported. + + +<sect1>Attribute map<p> + +The disassembler works by creating an attribute map for the whole address +space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an +external info file (if given) is read. Disassembly is done in several passes. +In all passes with the exception of the last one, information about the +disassembled code is gathered and added to the symbol and attribute maps. The +last pass generates output using the information from the maps. + +<sect1>Labels<p> + +Some instructions may generate labels in the first pass, while most other +instructions do not generate labels, but use them if they are available. Among +others, the branch and jump instructions will generate labels for the target +of the branch in the first pass. External labels (taken from the info file) +have precedence over internally generated ones, They must be valid identifiers +as specified for the ca65 assembler. Internal labels (generated by the +disassembler) have the form <tt/Labcd/, where <tt/abcd/ is the hexadecimal +address of the label in upper case letters. You should probably avoid using +such label names for external labels. + + +<sect1>Info File<p> + +The info file is used to pass additional information about the input code to +the disassembler. This includes label names, data areas or tables, and global +options like input and output file names. See the <ref id="infofile" +name="next section"> for more information. + + + +<sect>Info File Format<label id="infofile"><p> + +The info file contains lists of specifications grouped together. Each group +directive has an identifying token and an attribute list enclosed in curly +braces. Attributes have a name followed by a value. The syntax of the value +depends on the type of the attribute. String attributes are places in double +quotes, numeric attributes may be specified as decimal numbers or hexadecimal +with a leading dollar sign. There are also attributes where the attribute +value is a keyword, in this case the keyword is given as is (without quotes or +anything). Each attribute is terminated by a semicolon. + +<tscreen><verb> + group-name { attribute1 attribute-value; attribute2 attribute-value; } +</verb></tscreen> + + +<sect1>Comments<p> + +Comments start with a hash mark (<tt/#/) and extend from the position of +the mark to the end of the current line. Hash marks inside of strings will +of course <em/not/ start a comment. + + +<sect1>Specifying global options<label id="global-options"><p> + +Global options may be specified in a group with the name <tt/GLOBAL/. The +following attributes are recognized: + +<descrip> + + <tag><tt/ARGUMENTCOLUMN/</tag> + This attribute specifies the column in the output, where the argument for + an opcode or pseudo instruction starts. The corresponding command line + option is + <tt><ref id="option--argument-column" name="--argument-column"></tt>. + + + <tag><tt/COMMENTCOLUMN/</tag> + This attribute specifies the column in the output, where the comment starts + in a line. It is only used for in-line comments. The corresponding command + line option is + <tt><ref id="option--comment-column" name="--comment-column"></tt>. + + + <label id="COMMENTS"> + <tag><tt/COMMENTS/</tag> + This attribute may be used instead of the <tt><ref id="option--comments" + name="--comments"></tt> option on the command line. It takes a numerical + parameter between 0 and 4. Higher values increase the amount of information + written to the output file in form of comments. + + + <tag><tt/CPU/</tag> + This attribute may be used instead of the <tt><ref id="option--cpu" + name="--cpu"></tt> option on the command line. For possible values see + there. The value is a string and must be enclosed in quotes. + + + <tag><tt/HEXOFFS/</tag> + The attribute is followed by a boolean value. If true, offsets to labels are + output in hex, otherwise they're output in decimal notation. The default is + false. The attribute may be changed on the command line using the <tt><ref + id="option--hexoffs" name="--hexoffs"></tt> option. + + + <tag><tt/INPUTNAME/</tag> + The attribute is followed by a string value, which gives the name of the + input file to read. If it is present, the disassembler does not accept an + input file name on the command line. + + + <tag><tt/INPUTOFFS/</tag> + The attribute is followed by a numerical value that gives an offset into + the input file which is skipped before reading data. The attribute may be + used to skip headers or unwanted code sections in the input file. + + + <tag><tt/INPUTSIZE/</tag> + <tt/INPUTSIZE/ is followed by a numerical value that gives the amount of + data to read from the input file. Data beyond <tt/INPUTOFFS + INPUTSIZE/ + is ignored. + + + <label id="LABELBREAK"> + <tag><tt/LABELBREAK/</tag> + <tt/LABELBREAK/ is followed by a numerical value that specifies the label + length that will force a newline. To have all labels on their own lines, + you may set this value to zero. + + See also the <tt><ref id="option--label-break" name="--label-break"></tt> + command line option. A <tt/LABELBREAK/ statement in the info file will + override any value given on the command line. + + + <tag><tt/MNEMONICCOLUMN/</tag> + This attribute specifies the column in the output, where the mnemonic or + pseudo instruction is placed. The corresponding command line option is + <tt><ref id="option--mnemonic-column" name="--mnemonic-column"></tt>. + + + <tag><tt/NEWLINEAFTERJMP/</tag> + This attribute is followed by a boolean value. When true, a newline is + inserted after each <tt/JMP/ instruction. The default is false. + + + <tag><tt/NEWLINEAFTERRTS/</tag> + This attribute is followed by a boolean value. When true, a newline is + inserted after each <tt/RTS/ instruction. The default is false. + + + <label id="OUTPUTNAME"> + <tag><tt/OUTPUTNAME/</tag> + The attribute is followed by string value, which gives the name of the + output file to write. If it is present, specification of an output file on + the command line using the <tt><ref id="option-o" name="-o"></tt> option is + not allowed. + + The default is to use <tt/stdout/ for output, so without this attribute or + the corresponding command line option <tt/<ref id="option-o" name="-o">/ + the output will go to the terminal. + + + <tag><tt/PAGELENGTH/</tag> + This attribute may be used instead of the <tt><ref id="option--pagelength" + name="--pagelength"></tt> option on the command line. It takes a numerical + parameter. Using zero as page length (which is the default) means that no + pages are generated. + + + <tag><tt/STARTADDR/</tag> + This attribute may be used instead of the <tt><ref id="option--start-addr" + name="--start-addr"></tt> option on the command line. It takes a numerical + parameter. The default for the start address is $10000 minus the size of + the input file (this assumes that the input file is a ROM that contains the + reset and irq vectors). + + + <tag><tt/TEXTCOLUMN/</tag> + This attribute specifies the column, where the data bytes are output + translated into ASCII text. It is only used if + <tt><ref id="COMMENTS" name="COMMENTS"></tt> is set to at least 4. The + corresponding command line option is + <tt><ref id="option--text-column" name="--text-column"></tt>. + +</descrip> + + +<sect1>Specifying Ranges<p> + +The <tt/RANGE/ directive is used to give information about address ranges. The +following attributes are recognized: + +<descrip> + + <tag><tt>COMMENT</tt></tag> + This attribute is only allowed if a label is also given. It takes a string + as argument. See the description of the <tt><ref id="infofile-label" + name="LABEL"></tt> directive for an explanation. + + <tag><tt>END</tt></tag> + This gives the end address of the range. The end address is inclusive, that + means, it is part of the range. Of course, it may not be smaller than the + start address. + + <tag><tt>NAME</tt></tag> + This is a convenience attribute. It takes a string argument and will cause + the disassembler to define a label for the start of the range with the + given name. So a separate <tt><ref id="infofile-label" name="LABEL"></tt> + directive is not needed. + + <tag><tt>START</tt></tag> + This gives the start address of the range. + + <tag><tt>TYPE</tt></tag> + This attribute specifies the type of data within the range. The attribute + value is one of the following keywords: + + <descrip> + <tag><tt>ADDRTABLE</tt></tag> + The range consists of data and is disassembled as a table of words + (16 bit values). The difference to the <tt/WORDTABLE/ type is that + a label is defined for each entry in the table. + + <tag><tt>BYTETABLE</tt></tag> + The range consists of data and is disassembled as a byte table. + + <tag><tt>CODE</tt></tag> + The range consists of code. + + <tag><tt>DBYTETABLE</tt></tag> + The range consists of data and is disassembled as a table of dbytes + (double byte values, 16 bit values with the low byte containing the + most significant byte of the 16 bit value). + + <tag><tt>DWORDTABLE</tt></tag> + The range consists of data and is disassembled as a table of double + words (32 bit values). + + <tag><tt>RTSTABLE</tt></tag> + The range consists of data and is disassembled as a table of words (16 bit + values). The values are interpreted as words that are pushed onto the + stack and jump to it via <tt/RTS/. This means that they contain + <tt/address-1/ of a function, for which a label will get defined by the + disassembler. + + <tag><tt>SKIP</tt></tag> + The range is simply ignored when generating the output file. Please note + that this means that reassembling the output file will <em/not/ generate + the original file, not only because the missing piece in between, but also + because the following code will be located on wrong addresses. Output + generated with <tt/SKIP/ ranges will need manual rework. + + <tag><tt>TEXTTABLE</tt></tag> + The range consists of readable text. + + <tag><tt>WORDTABLE</tt></tag> + The range consists of data and is disassembled as a table of words + (16 bit values). + + </descrip> + +</descrip> + + +<sect1>Specifying Labels<label id="infofile-label"><p> + +The <tt/LABEL/ directive is used to give names for labels in the disassembled +code. The following attributes are recognized: + +<descrip> + + <tag><tt>ADDR</tt></tag> + Followed by a numerical value. Specifies the value of the label. + + <tag><tt>COMMENT</tt></tag> + Attribute argument is a string. The comment will show up in a separate line + before the label, if the label is within code or data range, or after the + label if it is outside. + + Example output: + +<tscreen><verb> + foo := $0001 ; Comment for label named "foo" + + ; Comment for label named "bar" + bar: +</verb></tscreen> + + <tag><tt>NAME</tt></tag> + The attribute is followed by a string value which gives the name of the + label. Empty names are allowed, in this case the disassembler will create + an unnamed label (see the assembler docs for more information about unnamed + labels). + + <tag><tt>SIZE</tt></tag> + This attribute is optional and may be used to specify the size of the data + that follows. If a size greater than 1 is specified, the disassembler will + create labels in the form <tt/label+offs/ for all bytes within the given + range, where <tt/label/ is the label name given with the <tt/NAME/ + attribute, and <tt/offs/ is the offset within the data. + +</descrip> + + +<sect1>Specifying Segments<label id="infofile-segment"><p> + +The <tt/SEGMENT/ directive is used to specify a segment within the +disassembled code. The following attributes are recognized: + +<descrip> + + <tag><tt>START</tt></tag> + Followed by a numerical value. Specifies the start address of the segment. + + <tag><tt>END</tt></tag> + Followed by a numerical value. Specifies the end address of the segment. The + end address is last the address that is part of the segment. + + <tag><tt>NAME</tt></tag> + The attribute is followed by a string value which gives the name of the + segment. +</descrip> + +All attributes are mandatory. Segments may not overlap. Since there is no +explicit "end this segment" pseudo op, the disassembler cannot notify the +assembler that one segment has ended. This may lead to errors if you don't +define your segments carefully. As a rule of thumb, if you're using segments, +your should define segments for all disassembled code. + + +<sect1>Specifying Assembler Includes<label id="infofile-asminc"><p> + +The <tt/ASMINC/ directive is used to give the names of input files containing +symbol assignments in assembler syntax: + +<tscreen><verb> + Name = value + Name := value +</verb></tscreen> + +The usual conventions apply for symbol names. Values may be specified as hex +(leading $), binary (leading %) or decimal. The values may optionally +be signed. + +NOTE: The include file parser is very simple. Expressions are not allowed, and +anything but symbol assignments is flagged as an error (but see the +<tt/IGNOREUNKNOWN/ directive below). + +The following attributes are recognized: + +<descrip> + + <tag><tt>FILE</tt></tag> + Followed by a string value. Specifies the name of the file to read. + + <tag><tt>COMMENTSTART</tt></tag> + The optional attribute is followed by a character constant. It specifies the + character that starts a comment. The default value is a semicolon. This + value is ignored if <tt/IGNOREUNKNOWN/ is true. + + <tag><tt>IGNOREUNKNOWN</tt></tag> + This attribute is optional and is followed by a boolean value. It allows to + ignore input lines that don't have a valid syntax. This allows to read in + assembler include files that contain more than just symbol assignments. + Note: When this attribute is used, the disassembler will ignore any errors + in the given include file. This may have undesired side effects. + +</descrip> + + +<sect1>An Info File Example<p> + +The following is a short example for an info file that contains most of the +directives explained above: + +<tscreen><verb> + # This is a comment. It extends to the end of the line + GLOBAL { + OUTPUTNAME "kernal.s"; + INPUTNAME "kernal.bin"; + STARTADDR $E000; + PAGELENGTH 0; # No paging + CPU "6502"; + }; + + # One segment for the whole stuff + SEGMENT { START $E000; END $FFFF; NAME kernal; }; + + RANGE { START $E612; END $E631; TYPE Code; }; + RANGE { START $E632; END $E640; TYPE ByteTable; }; + RANGE { START $EA51; END $EA84; TYPE RtsTable; }; + RANGE { START $EC6C; END $ECAB; TYPE RtsTable; }; + RANGE { START $ED08; END $ED11; TYPE AddrTable; }; + + # Zero page variables + LABEL { NAME "fnadr"; ADDR $90; SIZE 3; }; + LABEL { NAME "sal"; ADDR $93; }; + LABEL { NAME "sah"; ADDR $94; }; + LABEL { NAME "sas"; ADDR $95; }; + + # Stack + LABEL { NAME "stack"; ADDR $100; SIZE 255; }; + + # Indirect vectors + LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ + LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK + LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI + + # Jump table at end of kernal ROM + LABEL { NAME "kscrorg"; ADDR $FFED; }; + LABEL { NAME "kplot"; ADDR $FFF0; }; + LABEL { NAME "kiobase"; ADDR $FFF3; }; + LABEL { NAME "kgbye"; ADDR $FFF6; }; + + # Hardware vectors + LABEL { NAME "hanmi"; ADDR $FFFA; }; + LABEL { NAME "hares"; ADDR $FFFC; }; + LABEL { NAME "hairq"; ADDR $FFFE; }; +</verb></tscreen> + + + + + +<sect>Bugs/Feedback<p> + +If you have problems using the disassembler, if you find any bugs, or if +you're doing something interesting with the assembler, I would be glad to hear +from you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +da65 (and all cc65 binutils) are (C) Copyright 1998-2007 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + + + + diff --git a/doc/debugging.sgml b/doc/debugging.sgml new file mode 100644 index 000000000..7566370b9 --- /dev/null +++ b/doc/debugging.sgml @@ -0,0 +1,154 @@ +<!doctype linuxdoc system> + +<article> + +<title>Using emulators with cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>03.12.2000 + +<abstract> +How to debug your code using the VICE and Oricutron emulators. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This document describes how to debug your programs using the cc65 development +tools and the VICE CBM emulator. + + + +<sect>What is VICE?<p> + +VICE is an emulator for many of the CBM machines. It runs on Unix, MS-DOS, +Win32, OS/2, Acorn RISC OS, BeOS, QNX 6.x, Amiga, GP2X and Mac OS X. It emulates +the Commodore 64, 128, VIC20, PET and the 600/700 machines. For more information +see the VICE home page: + +<htmlurl url="http://www.viceteam.org/"> + +VICE has a builtin machine language monitor that may be used for debugging +your programs. Using an emulator for debugging has some advantages: + +<itemize> + +<item>Since you're using a crossassembler/-compiler anyway, you don't need to +transfer the program to the real machine until it is done. + +<item>An emulator allows many things that are almost impossible one of the +original machines. You may set watchpoints (detect read or write access to +arbitary addresses), debug interrupt handlers and even debug routines that run +inside the 1541 floppy. + +<item>You may use the label file generated by the linker to make much more use +from the monitor. + +</itemize> + + + +<sect>How to prepare your programs<p> + +VICE support is mostly done via a label file that is generated by the linker +and that may be read by the VICE monitor, so it knows about your program. +Source level debugging is <tt/not/ available, you have to debug your programs +in the assembler view. + +The first step is to generate object files that contain information about +<em/all/ labels in your sources, not just the exported ones. This can be done +by several means: + +<itemize> + +<item>Use the -g switch on the assembler command line. + +<item>Use the +<tscreen><verb> + .debuginfo + +</verb></tscreen> + command in your source. + +<item>Use the <tt/-g/ switch when invoking the compiler. The compiler will +then place a <tt/.debuginfo/ command into the generated assembler source. + +</itemize> + +So, if you have just C code, all you need is to invoke the compiler with +<tt/-g/. If you're using assembler code, you have to use <tt/-g/ for the +assembler, or add "<tt/.debuginfo on/" to your source files. Since the +generated debug info is not appended to the generated executables, it is a +good idea to always use <tt/-g/. It makes the object files and libraries +slightly larger (˜30%), but this is usually not a problem. + +The second step is to tell the linker that it should generate a VICE label +file. This is done by the <tt/-Ln/ switch followed by the name of the label +file (I'm usually using a <tt/.lbl/ extension for these files). An example for +a linker command line would be: + +<tscreen><verb> + ld65 -o hello -t c64 -Ln hello.lbl -m hello.map hello.o c64.lib +</verb></tscreen> +or +<tscreen><verb> + ld65 -o hello.tap -t atmos -Ln hello.sym -m hello.map hello.o atmos.lib +</verb></tscreen> + +This will generate a file named hello.lbl that contains all symbols used in +your program. + +<bf>Note</bf>: The runtime libraries and startup files were generated with +debug info, so you don't have to care about this. + + + +<sect>How to use the label file with VICE<p> + +Load your program, then enter the monitor and use the "<tt/ll/" command to +load your label file like this: + +<tscreen><verb> + ll "hello.lbl" +</verb></tscreen> + +You will get lots of warnings and even a few errors. You may ignore safely all +these warnings and errors as long as they reference any problems VICE thinks +it has with the labels. + +After loading the labels, they are used by VICE in the disassembler listing, +and you may use them whereever you need to specify an address. Try + +<tscreen><verb> + d ._main +</verb></tscreen> + +as an example (note that VICE needs a leading dot before all labels, and that +the compiler prepends an underline under most named labels). + + + +<sect>How to use the label file with Oricutron<p> + +Load your program, then enter the monitor and use the "<tt/sl/" command to +load your label file like this: + +<tscreen><verb> + sl hello.sym +</verb></tscreen> + +After loading the labels, they are used by Oricutron in the disassembler listing, +and you may use them whereever you need to specify an address. Try + +<tscreen><verb> + d ._main +</verb></tscreen> + +as an example (note that VICE needs a leading dot before all labels, and that +the compiler prepends an underline under most named labels). + + + +</article> diff --git a/doc/dio.sgml b/doc/dio.sgml new file mode 100644 index 000000000..f340fa254 --- /dev/null +++ b/doc/dio.sgml @@ -0,0 +1,134 @@ +<!doctype linuxdoc system> + +<article> +<title>Diskette Sector I/O Routines +<author>Christian Groessler, <htmlurl url="mailto:chris@groessler.org" name="chris@groessler.org"> +<date>20-Feb-2005 + +<abstract> +The cc65 library provides functions to read and write raw disk sectors. +Include the dio.h header file to get the necessary definitions. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Opening the disk for low level I/O<p> + +Prior to using these functions a handle to the device has to be obtained. This +is done with the <tt>dio_open</tt> function. After use, the handle should be +released with the <tt>dio_close</tt> function. + +<tscreen><verb> + dhandle_t __fastcall__ dio_open (unsigned char device); +</verb></tscreen> + +The <tt>device</tt> specifies the device to access, with 0 being the first +device, 1 the second, and so on. + +<tscreen><verb> + unsigned char __fastcall__ dio_close (dhandle_t handle); +</verb></tscreen> + +Closes a handle obtained by <tt>dio_open</tt>. Returns status code. +<p> + +<sect>Reading and writing sectors<p> + +The read and write functions are: + +<tscreen><verb> + unsigned char __fastcall__ dio_read (dhandle_t handle, + unsigned sect_num, + void *buffer); +</verb></tscreen> + +This function will read the sector specified by <tt>sect_num</tt> into the memory +location at buffer. + +<tscreen><verb> + unsigned char __fastcall__ dio_write (dhandle_t handle, + unsigned sect_num, + const void *buffer); +</verb></tscreen> + +This function will write the memory contents at buffer to the sector specified +by <tt>sect_num</tt>. No verify is performed. + +<tscreen><verb> + unsigned char __fastcall__ dio_write_verify (dhandle_t handle, + unsigned sect_num, + const void *buffer); +</verb></tscreen> + +This function will write the memory contents at buffer to the sector specified +by <tt>sect_num</tt>. A verification is performed. +<p> + +Use the <tt><ref name="dio_query_sectsize" id="sectsizecount"></tt> function to query +the size of a sector and the <tt><ref name="dio_query_sectcount" id="sectsizecount"></tt> +function to query the number of available sectors. +<p> + +All these functions will return 0 for success and an OS specific error code in +case of failure. +<p> + +<sect>Querying sector size and count<label id="sectsizecount"><p> + +Some systems support multiple diskette formats which have different sector sizes +and/or different sector counts. +<p> + +The following function returns the sector size of the currently inserted disk: + +<tscreen><verb> + unsigned __fastcall__ dio_query_sectsize (dhandle_t handle); +</verb></tscreen> + +On the Atari platform, the sector size is handled specially. Please refer +to the DIO section in the <htmlurl url="atari.html" name="Atari"> +specific platform documentation. +<p> + +The following function returns the sector count of the currently inserted disk: + +<tscreen><verb> + unsigned __fastcall__ dio_query_sectcount (dhandle_t handle); +</verb></tscreen> + +<sect>Converting sector numbers<p> + +Since the read and write functions expect a sector number, for systems where +the sectors aren't addressed by a logical sector number (e.g. CBM devices), +there are 2 conversion functions. One of them converts a logical sector number +to a head/track/sector triple. The other conversion function works the other +way round. + +<tscreen><verb> + unsigned char __fastcall__ dio_phys_to_log (dhandle_t handle, + const dio_phys_pos *physpos, + unsigned *sectnum); +</verb></tscreen> + +This function converts track/head/sector to logical sector number. + +<tscreen><verb> + unsigned char __fastcall__ dio_log_to_phys (dhandle_t handle, + const unsigned *sectnum, + dio_phys_pos *physpos); +</verb></tscreen> + +This function converts a logical sector number to track/head/sector notation. +<p> + +Note, that on systems which natively use logical sector numbers (e.g. Atari), +the conversion functions are dummies. They ignore head/track +(<tt>dio_phys_to_log</tt>) or return them as zero (<tt>dio_log_to_phys</tt>). +The logical sector number is returned as physical sector and vice versa. +<p> + + +</article> diff --git a/doc/funcref.sgml b/doc/funcref.sgml new file mode 100644 index 000000000..ba8fb8abc --- /dev/null +++ b/doc/funcref.sgml @@ -0,0 +1,7439 @@ +<!doctype linuxdoc system> <!-- -*- text-mode -*- --> + +<article> +<title>cc65 function reference +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>07.11.2002 + +<abstract> +cc65 is a C compiler for 6502 based systems. This function reference describes +the C functions available in the standard library. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Introduction<p> + +cc65 is a C compiler for 6502 based systems. It implements a subset of the ISO +C standard plus additional functions specially crafted for 6502 systems or +just some of the supported machines. This function refrence describes the +available functions together with any limitations. + +For an overview about the available libraries, their purpose, and any +differences to the ISO standard, please have a look at the <htmlurl +url="library.html" name="cc65 Library Overview">. + +<bf/Note:/ Standard C functions are listed here, but not described in detail. +Since these functions behave identical on all standard compliant systems, they +are described in any book covering standard C. + +Each entry for a function contains a detailed description + +<quote> +<descrip> +<tag/Function/Summary of what <bf/function/ does. +<tag/Header/The header file that contains the declaration. +<tag/Declaration/Describes the needed header files and declaration of the +function. +<tag/Description/Description of the function. +<tag/Limits/Limits. +<tag/Availability/The availability of the function. +<tag/See also/Other related functions. +<tag/Example/A piece of actual code using the function. +</descrip> +</quote> + + +<sect>Functions by header file<p> + +<sect1><tt/6502.h/<label id="6502.h"><p> + +<itemize> +<item><ref id="BRK" name="BRK"> +<item><ref id="CLI" name="CLI"> +<item><ref id="SEI" name="SEI"> +<item><ref id="_sys" name="_sys"> +<item><ref id="getcpu" name="getcpu"> +<item><ref id="reset_brk" name="reset_brk"> +<item><ref id="reset_irq" name="reset_irq"> +<item><ref id="set_brk" name="set_brk"> +<item><ref id="set_irq" name="set_irq"> +</itemize> + + +<sect1><tt/apple2.h/<label id="apple2.h"><p> + +<itemize> +<item>_dos_type +<item><ref id="get_ostype" name="get_ostype"> +<item>rebootafterexit +</itemize> + + +<sect1><tt/apple2enh.h/<label id="apple2enh.h"><p> + +<itemize> +<item>_dos_type +<item><ref id="get_ostype" name="get_ostype"> +<item>rebootafterexit +<item>textframe +<item>textframexy +<item><ref id="videomode" name="videomode"> +</itemize> + + +<sect1><tt/assert.h/<label id="assert.h"><p> + +<itemize> +<item><ref id="assert" name="assert"> +</itemize> + + +<sect1><tt/atari.h/<label id="atari.h"><p> + +<itemize> +<!-- <item><ref id="_getcolor" name="_getcolor"> --> +<!-- <item><ref id="_getdefdev" name="_getdefdev"> --> +<!-- <item><ref id="_graphics" name="_graphics"> --> +<!-- <item><ref id="_rest_vecs" name="_rest_vecs"> --> +<!-- <item><ref id="_save_vecs" name="_save_vecs"> --> +<!-- <item><ref id="_scroll" name="_scroll"> --> +<!-- <item><ref id="_setcolor" name="_setcolor"> --> +<!-- <item><ref id="_setcolor_low" name="_setcolor_low"> --> +<item><ref id="get_ostype" name="get_ostype"> +<!-- <item><ref id="get_tv" name="get_tv"> --> +</itemize> + +(incomplete) + + +<sect1><tt/atmos.h/<label id="atmos.h"><p> + +<itemize> +<item><ref id="atmos_load" name="atmos_load"> +<item><ref id="atmos_save" name="atmos_save"> +</itemize> + + +<sect1><tt/c128.h/<label id="c128.h"><p> + +<itemize> +<item><ref id="c64mode" name="c64mode"> +<item><ref id="fast" name="fast"> +<item><ref id="slow" name="slow"> +<item><ref id="toggle_videomode" name="toggle_videomode"> +<item><ref id="videomode" name="videomode"> +</itemize> + + +<sect1><tt/c16.h/<label id="c16.h"><p> + +(incomplete) + + +<sect1><tt/c64.h/<label id="c64.h"><p> + +<itemize> +<item><ref id="get_ostype" name="get_ostype"> +</itemize> + + +<sect1><tt/cbm.h/<label id="cbm.h"><p> + +<itemize> +<item><ref id="cbm_k_acptr" name="cbm_k_acptr"> +<item><ref id="cbm_k_basin" name="cbm_k_basin"> +<item><ref id="cbm_k_bsout" name="cbm_k_bsout"> +<item><ref id="cbm_k_chkin" name="cbm_k_chkin"> +<item><ref id="cbm_k_ciout" name="cbm_k_ciout"> +<item><ref id="cbm_k_ckout" name="cbm_k_ckout"> +<item><ref id="cbm_k_clall" name="cbm_k_clall"> +<item><ref id="cbm_k_close" name="cbm_k_close"> +<item><ref id="cbm_k_clrch" name="cbm_k_clrch"> +<item><ref id="cbm_k_getin" name="cbm_k_getin"> +<item><ref id="cbm_k_iobase" name="cbm_k_iobase"> +<item><ref id="cbm_k_listen" name="cbm_k_listen"> +<item><ref id="cbm_k_load" name="cbm_k_load"> +<item><ref id="cbm_k_open" name="cbm_k_open"> +<item><ref id="cbm_k_readst" name="cbm_k_readst"> +<item><ref id="cbm_k_save" name="cbm_k_save"> +<item><ref id="cbm_k_setlfs" name="cbm_k_setlfs"> +<item><ref id="cbm_k_setnam" name="cbm_k_setnam"> +<item><ref id="cbm_k_unlsn" name="cbm_k_unlsn"> +<!-- <item><ref id="cbm_load" name="cbm_load"> --> +<!-- <item><ref id="cbm_open" name="cbm_open"> --> +<!-- <item><ref id="cbm_opendir" name="cbm_opendir"> --> +<!-- <item><ref id="cbm_read" name="cbm_read"> --> +<!-- <item><ref id="cbm_readdir" name="cbm_readdir"> --> +<!-- <item><ref id="cbm_save" name="cbm_save"> --> +<!-- <item><ref id="cbm_write" name="cbm_write"> --> +</itemize> + +(incomplete) + + +<sect1><tt/cbm510.h/<label id="cbm510.h"><p> + +<itemize> +<item><ref id="peekbsys" name="peekbsys"> +<item><ref id="peekwsys" name="peekwsys"> +<item><ref id="pokebsys" name="pokebsys"> +<item><ref id="pokewsys" name="pokewsys"> +</itemize> + + +<sect1><tt/cbm610.h/<label id="cbm610.h"><p> + +<itemize> +<item><ref id="peekbsys" name="peekbsys"> +<item><ref id="peekwsys" name="peekwsys"> +<item><ref id="pokebsys" name="pokebsys"> +<item><ref id="pokewsys" name="pokewsys"> +</itemize> + + +<sect1><tt/cc65.h/<label id="cc65.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="cc65_cos" name="cc65_cos"> --> +<!-- <item><ref id="cc65_idiv32by16r16" name="cc65_idiv32by16r16"> --> +<!-- <item><ref id="cc65_imul16x16r32" name="cc65_imul16x16r32"> --> +<!-- <item><ref id="cc65_imul8x8r16" name="cc65_imul8x8r16"> --> +<!-- <item><ref id="cc65_sin" name="cc65_sin"> --> +<!-- <item><ref id="cc65_udiv32by16r16" name="cc65_udiv32by16r16"> --> +<!-- <item><ref id="cc65_umul16x16r32" name="cc65_umul16x16r32"> --> +<!-- <item><ref id="cc65_umul16x8r32" name="cc65_umul16x8r32"> --> +<!-- <item><ref id="cc65_umul8x8r16" name="cc65_umul8x8r16"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/conio.h/<label id="conio.h"><p> + +<itemize> +<item><ref id="bgcolor" name="bgcolor"> +<item><ref id="bordercolor" name="bordercolor"> +<item><ref id="cclear" name="cclear"> +<item><ref id="cclearxy" name="cclearxy"> +<item><ref id="cgetc" name="cgetc"> +<item><ref id="chline" name="chline"> +<item><ref id="chlinexy" name="chlinexy"> +<item><ref id="clrscr" name="clrscr"> +<item><ref id="cprintf" name="cprintf"> +<item><ref id="cputc" name="cputc"> +<item><ref id="cputcxy" name="cputcxy"> +<item><ref id="cputs" name="cputs"> +<item><ref id="cputsxy" name="cputsxy"> +<item><ref id="cursor" name="cursor"> +<item><ref id="cvline" name="cvline"> +<item><ref id="cvlinexy" name="cvlinexy"> +<item><ref id="gotox" name="gotox"> +<item><ref id="gotoxy" name="gotoxy"> +<item><ref id="gotoy" name="gotoy"> +<item><ref id="kbhit" name="kbhit"> +<item><ref id="revers" name="revers"> +<item><ref id="screensize" name="screensize"> +<item><ref id="textcolor" name="textcolor"> +<item><ref id="vcprintf" name="vcprintf"> +<item><ref id="wherex" name="wherex"> +<item><ref id="wherey" name="wherey"> +</itemize> + + +<sect1><tt/ctype.h/<label id="ctype.h"><p> + +<itemize> +<item><ref id="isalnum" name="isalnum"> +<item><ref id="isalpha" name="isalpha"> +<item><ref id="isascii" name="isascii"> +<item><ref id="isblank" name="isblank"> +<item><ref id="iscntrl" name="iscntrl"> +<item><ref id="isdigit" name="isdigit"> +<item><ref id="isgraph" name="isgraph"> +<item><ref id="islower" name="islower"> +<item><ref id="isprint" name="isprint"> +<item><ref id="ispunct" name="ispunct"> +<item><ref id="isspace" name="isspace"> +<item><ref id="isupper" name="isupper"> +<item><ref id="isxdigit" name="isxdigit"> +<item><ref id="tolower" name="tolower"> +<item><ref id="toupper" name="toupper"> +</itemize> + + +<sect1><tt/dbg.h/<label id="dbg.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="DbgInit" name="DbgInit"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/dio.h/<label id="dio.h"><p> + +<htmlurl url="dio.html" name="dio.html"> +Low-level disk I/O API. + + +<sect1><tt/dirent.h/<label id="dirent.h"><p> + +<itemize> +<item><ref id="_DE_ISDIR" name="_DE_ISDIR"> +<item><ref id="_DE_ISLBL" name="_DE_ISLBL"> +<item><ref id="_DE_ISLNK" name="_DE_ISLNK"> +<item><ref id="_DE_ISREG" name="_DE_ISREG"> +<item><ref id="closedir" name="closedir"> +<item><ref id="opendir" name="opendir"> +<item><ref id="readdir" name="readdir"> +<item><ref id="rewinddir" name="rewinddir"> +<item><ref id="seekdir" name="seekdir"> +<item><ref id="telldir" name="telldir"> +</itemize> + +(incomplete) + + +<sect1><tt/em.h/<label id="em.h"><p> + +<itemize> +<item><ref id="em_commit" name="em_commit"> +<item><ref id="em_copyfrom" name="em_copyfrom"> +<item><ref id="em_copyto" name="em_copyto"> +<item><ref id="em_install" name="em_install"> +<item><ref id="em_load_driver" name="em_load_driver"> +<item><ref id="em_map" name="em_map"> +<item><ref id="em_pagecount" name="em_pagecount"> +<item><ref id="em_uninstall" name="em_uninstall"> +<item><ref id="em_unload" name="em_unload"> +<item><ref id="em_use" name="em_use"> +</itemize> + + +<sect1><tt/errno.h/<label id="errno.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="_directerrno" name="_directerrno"> --> +<!-- <item><ref id="_mappederrno" name="_mappederrno"> --> +<!-- <item><ref id="_osmaperrno" name="_osmaperrno"> --> +<!-- <item><ref id="_seterrno" name="_seterrno"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/fcntl.h/<label id="fcntl.h"><p> + +<itemize> +<item><ref id="close" name="close"> +<item><ref id="creat" name="creat"> +<item><ref id="open" name="open"> +</itemize> + + +<sect1><tt/geos.h/<label id="geos.h"><p> + +(incomplete) + + +<sect1><tt/joystick.h/<label id="joystick.h"><p> + +<itemize> +<item><ref id="joy_count" name="joy_count"> +<item><ref id="joy_install" name="joy_install"> +<item><ref id="joy_load_driver" name="joy_load_driver"> +<item><ref id="joy_read" name="joy_read"> +<item><ref id="joy_uninstall" name="joy_uninstall"> +<item><ref id="joy_unload" name="joy_unload"> +</itemize> + + +<sect1><tt/locale.h/<label id="locale.h"><p> + +<itemize> +<item><ref id="localeconv" name="localeconv"> +<item><ref id="setlocale" name="setlocale"> +</itemize> + + +<sect1><tt/lynx.h/<label id="lynx.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="lynx_eeprom_erase" name="lynx_eeprom_erase"> --> +<!-- <item><ref id="lynx_eeprom_read" name="lynx_eeprom_read"> --> +<!-- <item><ref id="lynx_eeprom_write" name="lynx_eeprom_write"> --> +<!-- <item><ref id="lynx_eeread" name="lynx_eeread"> --> +<!-- <item><ref id="lynx_eewrite" name="lynx_eewrite"> --> +<!-- <item><ref id="lynx_exec" name="lynx_exec"> --> +<!-- <item><ref id="lynx_load" name="lynx_load"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/modload.h/<label id="modload.h"><p> + +<itemize> +<item><ref id="mod_load" name="mod_load"> +<item><ref id="mod_free" name="mod_free"> +</itemize> + + +<sect1><tt/mouse.h/<label id="mouse.h"><p> + +<itemize> +<item><ref id="mouse_buttons" name="mouse_buttons"> +<item><ref id="mouse_getbox" name="mouse_getbox"> +<item><ref id="mouse_geterrormsg" name="mouse_geterrormsg"> +<item><ref id="mouse_hide" name="mouse_hide"> +<item><ref id="mouse_info" name="mouse_info"> +<item><ref id="mouse_install" name="mouse_install"> +<item><ref id="mouse_ioctl" name="mouse_ioctl"> +<item><ref id="mouse_load_driver" name="mouse_load_driver"> +<item><ref id="mouse_move" name="mouse_move"> +<item><ref id="mouse_pos" name="mouse_pos"> +<item><ref id="mouse_setbox" name="mouse_setbox"> +<item><ref id="mouse_show" name="mouse_show"> +<item><ref id="mouse_uninstall" name="mouse_uninstall"> +<item><ref id="mouse_unload" name="mouse_unload"> +</itemize> + + +<sect1><tt/nes.h/<label id="nes.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="get_tv" name="get_tv"> --> +<!-- <item><ref id="waitvblank" name="waitvblank"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect1><tt/o65.h/<label id="o65.h"><p> + +The <tt/o65.h/ header file contains structure and constant definitions that +may be used when dealing with files in <htmlurl +url="http://www.6502.org/users/andre/o65/fileformat.html" name="o65 format">. +It does not declare any functions. + + +<sect1><tt/peekpoke.h/<label id="peekpoke.h"><p> + +<itemize> +<item><ref id="PEEK" name="PEEK"> +<item><ref id="PEEKW" name="PEEKW"> +<item><ref id="POKE" name="POKE"> +<item><ref id="POKEW" name="POKEW"> +</itemize> + + +<sect1><tt/pet.h/<label id="pet.h"><p> + +(incomplete) + + +<sect1><tt/plus4.h/<label id="plus4.h"><p> + +(incomplete) + + +<sect1><tt/serial.h/<label id="serial.h"><p> + +The <tt/serial.h/ header file contains definitions for initializing serial +communication. + +<itemize> +<item><ref id="ser_close" name="ser_close"> +<item><ref id="ser_get" name="ser_get"> +<item><ref id="ser_install" name="ser_install"> +<item><ref id="ser_ioctl" name="ser_ioctl"> +<item><ref id="ser_load_driver" name="ser_load_driver"> +<item><ref id="ser_open" name="ser_open"> +<item><ref id="ser_put" name="ser_put"> +<item><ref id="ser_status" name="ser_status"> +<item><ref id="ser_uninstall" name="ser_uninstall"> +<item><ref id="ser_unload" name="ser_unload"> +</itemize> + + +<sect1><tt/setjmp.h/<label id="setjmp.h"><p> + +<itemize> +<item><ref id="setjmp" name="setjmp"> +<item><ref id="longjmp" name="longjmp"> +</itemize> + + +<sect1><tt/signal.h/<label id="signal.h"><p> + +<itemize> +<item><ref id="raise" name="raise"> +<item><ref id="signal" name="signal"> +</itemize> + + +<sect1><tt/stdarg.h/<label id="stdarg.h"><p> + +(incomplete) + + +<sect1><tt/stdbool.h/<label id="stdbool.h"><p> + +(incomplete) + + +<sect1><tt/stddef.h/<label id="stddef.h"><p> + +<itemize> +<item><ref id="offsetof" name="offsetof"> +</itemize> + + +<sect1><tt/stdio.h/<label id="stdio.h"><p> + +<itemize> +<item><ref id="_poserror" name="_poserror"> +<item><ref id="clearerr" name="clearerr"> +<!-- <item><ref id="fclose" name="fclose"> --> +<!-- <item><ref id="fdopen" name="fdopen"> --> +<item><ref id="feof" name="feof"> +<item><ref id="ferror" name="ferror"> +<!-- <item><ref id="fflush" name="fflush"> --> +<!-- <item><ref id="fgetc" name="fgetc"> --> +<!-- <item><ref id="fgetpos" name="fgetpos"> --> +<!-- <item><ref id="fgets" name="fgets"> --> +<item><ref id="fileno" name="fileno"> +<!-- <item><ref id="fopen" name="fopen"> --> +<!-- <item><ref id="fprintf" name="fprintf"> --> +<!-- <item><ref id="fputc" name="fputc"> --> +<!-- <item><ref id="fputs" name="fputs"> --> +<!-- <item><ref id="fread" name="fread"> --> +<!-- <item><ref id="freopen" name="freopen"> --> +<!-- <item><ref id="fscanf" name="fscanf"> --> +<!-- <item><ref id="fseek" name="fseek"> --> +<!-- <item><ref id="fsetpos" name="fsetpos"> --> +<!-- <item><ref id="ftell" name="ftell"> --> +<!-- <item><ref id="fwrite" name="fwrite"> --> +<!-- <item><ref id="getc" name="getc"> --> +<!-- <item><ref id="getchar" name="getchar"> --> +<!-- <item><ref id="gets" name="gets"> --> +<!-- <item><ref id="printf" name="printf"> --> +<!-- <item><ref id="putc" name="putc"> --> +<!-- <item><ref id="putchar" name="putchar"> --> +<!-- <item><ref id="puts" name="puts"> --> +<item><ref id="rename" name="rename"> +<item><ref id="remove" name="remove"> +<!-- <item><ref id="rewind" name="rewind"> --> +<!-- <item><ref id="scanf" name="scanf"> --> +<!-- <item><ref id="snprintf" name="snprintf"> --> +<!-- <item><ref id="sprintf" name="sprintf"> --> +<!-- <item><ref id="sscanf" name="sscanf"> --> +<!-- <item><ref id="vfprintf" name="vfprintf"> --> +<!-- <item><ref id="vfscanf" name="vfscanf"> --> +<!-- <item><ref id="vprintf" name="vprintf"> --> +<!-- <item><ref id="vscanf" name="vscanf"> --> +<!-- <item><ref id="vsnprintf" name="vsnprintf"> --> +<!-- <item><ref id="vsprintf" name="vsprintf"> --> +<!-- <item><ref id="vsscanf" name="vsscanf"> --> +</itemize> + +(incomplete) + + +<sect1><tt/stdlib.h/<label id="stdlib.h"><p> + +<itemize> +<item><ref id="_heapadd" name="_heapadd"> +<item><ref id="_heapblocksize" name="_heapblocksize"> +<item><ref id="_heapmaxavail" name="_heapmaxavail"> +<item><ref id="_heapmemavail" name="_heapmemavail"> +<item><ref id="_randomize" name="_randomize"> +<item><ref id="_swap" name="_swap"> +<item><ref id="abort" name="abort"> +<item><ref id="abs" name="abs"> +<item><ref id="atexit" name="atexit"> +<item><ref id="atoi" name="atoi"> +<item><ref id="atol" name="atol"> +<item><ref id="bsearch" name="bsearch"> +<item><ref id="calloc" name="calloc"> +<item><ref id="div" name="div"> +<item><ref id="exit" name="exit"> +<item><ref id="free" name="free"> +<item><ref id="getenv" name="getenv"> +<item><ref id="itoa" name="itoa"> +<item><ref id="labs" name="labs"> +<item><ref id="ltoa" name="ltoa"> +<item><ref id="malloc" name="malloc"> +<item><ref id="perror" name="perror"> +<!-- <item><ref id="posix_memalign" name="posix_memalign"> --> +<!-- <item><ref id="putenv" name="putenv"> --> +<item><ref id="qsort" name="qsort"> +<item><ref id="rand" name="rand"> +<item><ref id="realloc" name="realloc"> +<item><ref id="srand" name="srand"> +<!-- <item><ref id="system" name="system"> --> +<item><ref id="ultoa" name="ultoa"> +<item><ref id="utoa" name="utoa"> +</itemize> + +(incomplete) + + +<sect1><tt/string.h/<label id="string.h"><p> + +<itemize> +<item><ref id="_stroserror" name="_stroserror"> +<item><ref id="bzero" name="bzero"> +<item><ref id="memchr" name="memchr"> +<item><ref id="memcmp" name="memcmp"> +<item><ref id="memcpy" name="memcpy"> +<item><ref id="memmove" name="memmove"> +<item><ref id="memset" name="memset"> +<item><ref id="strcasecmp" name="strcasecmp"> +<item><ref id="strcat" name="strcat"> +<item><ref id="strchr" name="strchr"> +<item><ref id="strcmp" name="strcmp"> +<item><ref id="strcoll" name="strcoll"> +<item><ref id="strcpy" name="strcpy"> +<item><ref id="strcspn" name="strcspn"> +<item><ref id="strdup" name="strdup"> +<item><ref id="strerror" name="strerror"> +<item><ref id="stricmp" name="stricmp"> +<item><ref id="strlen" name="strlen"> +<item><ref id="strlower" name="strlower"> +<item><ref id="strlwr" name="strlwr"> +<item><ref id="strncat" name="strncat"> +<item><ref id="strncmp" name="strncmp"> +<item><ref id="strncpy" name="strncpy"> +<item><ref id="strrchr" name="strrchr"> +<item><ref id="strspn" name="strspn"> +<item><ref id="strstr" name="strstr"> +<item><ref id="strtok" name="strtok"> +<item><ref id="strxfrm" name="strxfrm"> +<item><ref id="strupper" name="strupper"> +<item><ref id="strupr" name="strupr"> +</itemize> + +(incomplete) + + +<sect1><tt/tgi.h/<label id="tgi.h"><p> + +<itemize> +<item><ref id="tgi_arc" name="tgi_arc"> +<item><ref id="tgi_bar" name="tgi_bar"> +<item><ref id="tgi_circle" name="tgi_circle"> +<item><ref id="tgi_clear" name="tgi_clear"> +<item><ref id="tgi_done" name="tgi_done"> +<item><ref id="tgi_ellipse" name="tgi_ellipse"> +<item><ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> +<item><ref id="tgi_getaspectratio" name="tgi_getaspectratio"> +<item><ref id="tgi_getcolor" name="tgi_getcolor"> +<item><ref id="tgi_getcolorcount" name="tgi_getcolorcount"> +<item><ref id="tgi_getdefpalette" name="tgi_getdefpalette"> +<item><ref id="tgi_geterror" name="tgi_geterror"> +<item><ref id="tgi_geterrormsg" name="tgi_geterrormsg"> +<item><ref id="tgi_getmaxcolor" name="tgi_getmaxcolor"> +<item><ref id="tgi_getmaxx" name="tgi_getmaxx"> +<item><ref id="tgi_getmaxy" name="tgi_getmaxy"> +<item><ref id="tgi_getpagecount" name="tgi_getpagecount"> +<item><ref id="tgi_getpalette" name="tgi_getpalette"> +<item><ref id="tgi_getpixel" name="tgi_getpixel"> +<item><ref id="tgi_gettextheight" name="tgi_gettextheight"> +<item><ref id="tgi_gettextwidth" name="tgi_gettextwidth"> +<item><ref id="tgi_getxres" name="tgi_getxres"> +<item><ref id="tgi_getyres" name="tgi_getyres"> +<item><ref id="tgi_gotoxy" name="tgi_gotoxy"> +<item><ref id="tgi_init" name="tgi_init"> +<item><ref id="tgi_install" name="tgi_install"> +<item><ref id="tgi_install_vectorfont" name="tgi_install_vectorfont"> +<item><ref id="tgi_ioctl" name="tgi_ioctl"> +<item><ref id="tgi_line" name="tgi_line"> +<item><ref id="tgi_lineto" name="tgi_lineto"> +<item><ref id="tgi_load_driver" name="tgi_load_driver"> +<item><ref id="tgi_load_vectorfont" name="tgi_load_vectorfont"> +<item><ref id="tgi_outtext" name="tgi_outtext"> +<item><ref id="tgi_outtextxy" name="tgi_outtextxy"> +<item><ref id="tgi_setaspectratio" name="tgi_setaspectratio"> +<item><ref id="tgi_setcolor" name="tgi_setcolor"> +<item><ref id="tgi_setdrawpage" name="tgi_setdrawpage"> +<item><ref id="tgi_setpalette" name="tgi_setpalette"> +<item><ref id="tgi_setpixel" name="tgi_setpixel"> +<item><ref id="tgi_setviewpage" name="tgi_setviewpage"> +<item><ref id="tgi_settextscale" name="tgi_settextscale"> +<item><ref id="tgi_settextstyle" name="tgi_settextstyle"> +<item><ref id="tgi_uninstall" name="tgi_uninstall"> +<item><ref id="tgi_unload" name="tgi_unload"> +</itemize> + +<sect1><tt/time.h/<label id="time.h"><p> + +<itemize> +<!-- <item><ref id="_systime" name="_systime"> --> +<!-- <item><ref id="asctime" name="asctime"> --> +<item><ref id="clock" name="clock"> +<!-- <item><ref id="ctime" name="ctime"> --> +<!-- <item><ref id="gmtime" name="gmtime"> --> +<!-- <item><ref id="localtime" name="localtime"> --> +<!-- <item><ref id="mktime" name="mktime"> --> +<!-- <item><ref id="strftime" name="strftime"> --> +<item><ref id="time" name="time"> +</itemize> + +(incomplete) + + +<sect1><tt/unistd.h/<label id="unistd.h"><p> + +<itemize> +<!-- <item><ref id="chdir" name="chdir"> --> +<item><ref id="exec" name="exec"> +<!-- <item><ref id="getcwd" name="getcwd"> --> +<item><ref id="getopt" name="getopt"> +<!-- <item><ref id="lseek" name="lseek"> --> +<!-- <item><ref id="mkdir" name="mkdir"> --> +<!-- <item><ref id="read" name="read"> --> +<!-- <item><ref id="rmdir" name="rmdir"> --> +<item><ref id="sleep" name="sleep"> +<item><ref id="unlink" name="unlink"> +<!-- <item><ref id="write" name="write"> --> +</itemize> + +(incomplete) + + +<sect1><tt/vic20.h/<label id="vic20.h"><p> + +(incomplete) + + +<sect1><tt/zlib.h/<label id="zlib.h"><p> + +<!-- <itemize> --> +<!-- <item><ref id="adler32" name="adler32"> --> +<!-- <item><ref id="crc32" name="crc32"> --> +<!-- <item><ref id="inflatemem" name="inflatemem"> --> +<!-- <item><ref id="uncompress" name="uncompress"> --> +<!-- </itemize> --> + +(incomplete) + + +<sect>Alphabetical function reference<p> + +<sect1>_DE_ISDIR<label id="_DE_ISDIR"><p> + +<quote> +<descrip> +<tag/Function/Determine if a directory entry specifies a directory. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int _DE_ISDIR(unsigned char type);/ +<tag/Description/The function is called with the type of a directory entry +taken from a <tt/struct dirent/ and returns true if the entry designates +a directory. +<tag/Limits/ +<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_DE_ISLBL" name="_DE_ISLBL">, +<ref id="_DE_ISLNK" name="_DE_ISLNK">, +<ref id="_DE_ISREG" name="_DE_ISREG"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_DE_ISLBL<label id="_DE_ISLBL"><p> + +<quote> +<descrip> +<tag/Function/Determine if a directory entry specifies a disk label. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int _DE_ISLBL(unsigned char type);/ +<tag/Description/The function is called with the type of a directory entry +taken from a <tt/struct dirent/ and returns true if the entry designates +a disk label. +<tag/Limits/ +<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_DE_ISDIR" name="_DE_ISDIR">, +<ref id="_DE_ISLNK" name="_DE_ISLNK">, +<ref id="_DE_ISREG" name="_DE_ISREG"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_DE_ISLNK<label id="_DE_ISLNK"><p> + +<quote> +<descrip> +<tag/Function/Determine if a directory entry specifies a link. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int _DE_ISLNK(unsigned char type);/ +<tag/Description/The function is called with the type of a directory entry +taken from a <tt/struct dirent/ and returns true if the entry designates +a link. +<tag/Limits/ +<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_DE_ISDIR" name="_DE_ISDIR">, +<ref id="_DE_ISLBL" name="_DE_ISLBL">, +<ref id="_DE_ISREG" name="_DE_ISREG"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_DE_ISREG<label id="_DE_ISREG"><p> + +<quote> +<descrip> +<tag/Function/Determine if a directory entry specifies a regular file. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int _DE_ISREG(unsigned char type);/ +<tag/Description/The function is called with the type of a directory entry +taken from a <tt/struct dirent/ and returns true if the entry designates +a regular file. +<tag/Limits/ +<itemize> +<item>The function is actually a macro. +<item>A "regular file" means anything with data in it. This might still mean +that special processing is needed, when accessing the file. Relative files of +the CBM systems are classified as being "regular" files, for example. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_DE_ISDIR" name="_DE_ISDIR">, +<ref id="_DE_ISLBL" name="_DE_ISLBL">, +<ref id="_DE_ISLNK" name="_DE_ISLNK"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_heapadd<label id="_heapadd"><p> + +<quote> +<descrip> +<tag/Function/Add a block to the heap. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ _heapadd (void* mem, size_t size);/ +<tag/Description/The function adds a block of raw memory to the heap. +<tag/Limits/ +<itemize> +<item>The minimum blocksize that can be added is 6 bytes; the function will +ignore smaller blocks. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_heapblocksize<label id="_heapblocksize"><p> + +<quote> +<descrip> +<tag/Function/Return the size of an allocated block. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/size_t __fastcall__ _heapblocksize (const void* block);/ +<tag/Description/The function returns the size of a block that must have +previously been allocated by <tt/<ref id="malloc" name="malloc">/, <tt/<ref +id="calloc" name="calloc">/ or <tt/<ref id="realloc" name="realloc">/. +<tag/Limits/ +<itemize> +<item>Passing a pointer to a block that was is not the result of one of the +allocation functions, or that has been free'd will give unpredicable results. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_heapmaxavail<label id="_heapmaxavail"><p> + +<quote> +<descrip> +<tag/Function/Return the largest block that is available on the heap. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/size_t _heapmaxavail (void);/ +<tag/Description/The function returns the size of the largest block that may +be allocated from the heap using <tt/<ref id="malloc" name="malloc">/. +<tag/Availability/cc65 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_heapmemavail<label id="_heapmemavail"><p> + +<quote> +<descrip> +<tag/Function/Return the total available space on the heap. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/size_t __fastcall__ _heapmemavail (void);/ +<tag/Description/The function returns the total number of bytes available on +the heap. +<tag/Limits/ +<itemize> +<item>This function is of less use than usually assumed, since the returned +heap space may be available but not in one block. So even if this function +says that several times more heap space is available than needed, <ref +id="malloc" name="malloc"> may still return <tt/NULL/. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_poserror<label id="_poserror"><p> + +<quote> +<descrip> +<tag/Function/Print an error message for the error in <tt/_oserror/. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/void __fastcall__ _poserror (const char* msg);/ +<tag/Description/<tt/_poserror/ prints an error message to <tt/stderr/. If +<tt/msg/ is not <tt/NULL/ and not an empty string, it is printed followed by +a colon and a blank. Then the error message for the current contents of +<tt/_oserror/ are printed followed by a newline. The message output is the +same as returned by <tt/<ref id="_stroserror" name="_stroserror">/ with an +argument of <tt/_oserror/. +<tag/Limits/ +<itemize> +<item>Since operating system specific error code are - you guessed it - +operating system specific, the value in <tt/_oserror/ and the message that is +printed depends on the cc65 target. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_stroserror" name="_stroserror">, +<ref id="perror" name="perror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_randomize<label id="_randomize"><p> + +<quote> +<descrip> +<tag/Function/Initialize the pseudo random number generator. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void _randomize (void);/ +<tag/Description/The function initializes the random number generator with +a seed derived from fast changing hardware events, so the seed itself can be +considered random to a certain degree. +<tag/Limits/<itemize> +<item>The randomness of the seed depends on the machine hardware. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="rand" name="rand">, +<ref id="srand" name="srand"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_stroserror<label id="_stroserror"><p> + +<quote> +<descrip> +<tag/Function/Return a string describing an OS specific error code. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/const char* __fastcall__ _stroserror (unsigned char errcode);/ +<tag/Description/<tt/_stroserror/ will return a string describing the given +operating system specific error code. +<tag/Limits/<itemize> +<item>Since operating system specific error code are - you guessed it - +operating system specific, the parameter and the string returned depend on the +cc65 target. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strerror" name="strerror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_swap<label id="_swap"><p> + +<quote> +<descrip> +<tag/Function/Swap the contents of memory areas. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ _swap (void* p, void* q, size_t size);/ +<tag/Description/<tt/_swap/ will swap (exchange) the contents of the two memory +areas pointed to by <tt/p/ and <tt/q/. Both memory areas are assumed to be +<tt/size/ bytes in size. +<tag/Limits/<itemize> +<item>The memory areas may not overlap, otherwise the results are undefined. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="memcpy" name="memcpy">, +<ref id="memmove" name="memmove"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>_sys<label id="_sys"><p> + +<quote> +<descrip> +<tag/Function/Call a subroutine passing register values. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void __fastcall__ _sys (struct regs* r);/ +<tag/Description/The function will call the subroutine at the address +specified in the <tt/pc/ member of the passed <tt/regs/ structure. All +registers and the CPU flags are set to the values given in the <tt/regs/ +structure. On return from the subroutine, the new values of the registers and +flags are stored back overwriting the old values. +<tag/Limits/<itemize> +<item>Bits 4 and 5 of the flags value in the <tt/regs/ structure are ignored +when calling the subroutine (they are unchanged from their current values). +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>BRK<label id="BRK"><p> + +<quote> +<descrip> +<tag/Function/Insert a 6502 BRK instrunction into the code. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void BRK (void);/ +<tag/Description/The function will insert a 6502 BRK instruction into the code +which may be used to trigger a debugger. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>The inserted instruction may lead to unexpected results if no debugger +is present. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="CLI" name="CLI">, +<ref id="SEI" name="SEI"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>CLI<label id="CLI"><p> + +<quote> +<descrip> +<tag/Function/Insert a 6502 CLI instrunction into the code. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void CLI (void);/ +<tag/Description/The function will insert a 6502 CLI instruction into the code, +so interrupts are enabled. Enabling interrupts has no effects if they are +already enabled (the default). +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>Disabling interrupts may lead to unexpected results. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="BRK" name="BRK">, +<ref id="SEI" name="SEI"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>PEEK<label id="PEEK"><p> + +<quote> +<descrip> +<tag/Function/Read a byte from memory. +<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ +<tag/Declaration/<tt/unsigned char PEEK (unsigned addr);/ +<tag/Description/The function will read the absolute memory given by <tt/addr/ +and return the value read. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>This function depends highly on the platform and environment. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEKW" name="PEEKW">, +<ref id="POKE" name="POKE"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>PEEKW<label id="PEEKW"><p> + +<quote> +<descrip> +<tag/Function/Read a word (two bytes) from memory. +<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ +<tag/Declaration/<tt/unsigned PEEKW (unsigned addr);/ +<tag/Description/The function will read the absolute memory given by <tt/addr/ +and return the value read. The byte read from the higher address is the high +byte of the return value. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>This function depends highly on the platform and environment. +<item>The order in which the two bytes are read is unspecified and may +depend of the address expression used. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="POKE" name="POKE"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>POKE<label id="POKE"><p> + +<quote> +<descrip> +<tag/Function/Write a byte to memory. +<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ +<tag/Declaration/<tt/void POKE (unsigned addr, unsigned char val);/ +<tag/Description/The function writes the value <tt/val/ to the absolute +memory address given by <tt/addr/. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>This function depends highly on the platform and environment. +<item>Careless use will cause the program to act strange or may crash the +machine. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="POKEW" name="POKEW"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>POKEW<label id="POKEW"><p> + +<quote> +<descrip> +<tag/Function/Write a word (two bytes) to memory. +<tag/Header/<tt/<ref id="peekpoke.h" name="peekpoke.h">/ +<tag/Declaration/<tt/void POKEW (unsigned addr, unsigned val);/ +<tag/Description/The function writes the value <tt/val/ to the absolute +memory address given by <tt/addr/. The low byte of <tt/val/ is written to +the <tt/addr/, the high byte is written to <tt/addr+1/. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>This function depends highly on the platform and environment. +<item>Careless use will cause the program to act strange or may crash the +machine. +<item>The order in which the two bytes are written is unspecified and may +depend of the address expression used. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="POKE" name="POKE"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>SEI<label id="SEI"><p> + +<quote> +<descrip> +<tag/Function/Insert a 6502 SEI instrunction into the code. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void SEI (void);/ +<tag/Description/The function will insert a 6502 SEI instruction into the code, +so interrupts are disabled. Note that non maskable interrupts cannot be +disabled. +<tag/Limits/<itemize> +<item>The function is actually a macro. +<item>Disabling interrupts may lead to unexpected results. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="BRK" name="BRK">, +<ref id="CLI" name="CLI"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>abort<label id="abort"><p> + +<quote> +<descrip> +<tag/Function/Terminates a program abnormally. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void abort (void);/ +<tag/Description/<tt/abort/ raises <tt/SIGABRT/, writes a termination message +on stderr, then terminates the program with an exit code of 3. +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="assert" name="assert">, +<ref id="exit" name="exit">, +<ref id="raise" name="raise"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>abs<label id="abs"><p> + +<quote> +<descrip> +<tag/Function/Returns the absolute value of an integer. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/int __fastcall__ abs (int v);/ +<tag/Description/<tt/abs/ returns the absolute value of the argument passed to +the function. +<tag/Limits/<itemize> +<item>The return value is undefined if <tt/INT_MIN/ is passed to the function. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="labs" name="labs"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>assert<label id="assert"><p> + +<quote> +<descrip> +<tag/Function/Test a condition and possibly abort. +<tag/Header/<tt/<ref id="assert.h" name="assert.h">/ +<tag/Declaration/<tt/void assert (int cond);/ +<tag/Description/<tt/assert/ is a macro that expands to a <tt/id/ +statement. If the condition evaluates t zero (false), assert prints a message +on stderr and aborts the program. +<tag/Limits/<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="exit" name="exit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>atexit<label id="atexit"><p> + +<quote> +<descrip> +<tag/Function/Register an exit function. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/int __fastcall__ atexit (void (*exitfunc) (void));/ +<tag/Description/<tt/atexit/ registers the function pointed to by +<tt/exitfunc/ as an exit function. Exit functions are called when the program +terminates, they are called in LIFO order (the last function registered is +called first). <tt/atexit/ returns zero on success and a nonzero value on +failure. +<tag/Limits/<itemize> +<item>A maximum of 5 exit functions can be registered. +<item>There is no way to unregister an exit function. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="exit" name="exit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>atmos_load<label id="atmos_load"><p> + +<quote> +<descrip> +<tag/Function/Load Atmos tape. +<tag/Header/<tt/<ref id="atmos.h" name="atmos.h">/ +<tag/Declaration/<tt/void __fastcall__ atmos_load(const char* name);/ +<tag/Description/<tt/atmos_load/ reads a memory block from tape. +<tag/Availability/cc65 +<tag/See also/ +<ref id="atmos_save" name="atmos_save"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>atmos_save<label id="atmos_save"><p> + +<quote> +<descrip> +<tag/Function/Save Atmos tape. +<tag/Header/<tt/<ref id="atmos.h" name="atmos.h">/ +<tag/Declaration/<tt/void __fastcall__ atmos_save(const char* name, const void* start, const void* end);/ +<tag/Description/<tt/atmos_save/ writes a memory block to tape. +<tag/Availability/cc65 +<tag/See also/ +<ref id="atmos_load" name="atmos_load"> +<tag/Example/<verb> +atmos_save("hires", 0xa000, 0xc000); +</verb> +</descrip> +</quote> + + +<sect1>atoi<label id="atoi"><p> + +<quote> +<descrip> +<tag/Function/Convert a string to an integer. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/int __fastcall__ atoi (const char* s);/ +<tag/Description/<tt/atoi/ converts the given string into an integer. +Conversion stops as soon as any invalid character is encountered. +<tag/Limits/<itemize> +<item>There is no way to detect any conversion errors. +<item>The function does not check for an numerical overflow when converting. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="atol" name="atol">, +<ref id="itoa" name="itoa">, +<ref id="ltoa" name="ltoa">, +<ref id="ultoa" name="ultoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>atol<label id="atol"><p> + +<quote> +<descrip> +<tag/Function/Convert a string to a long integer. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/long __fastcall__ atol (const char* s);/ +<tag/Description/<tt/atol/ converts the given string into a long integer. +Conversion stops as soon as any invalid character is encountered. +<tag/Limits/<itemize> +<item>There is no way to detect any conversion errors. +<item>The function does not check for an numerical overflow when converting. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="itoa" name="itoa">, +<ref id="ltoa" name="ltoa">, +<ref id="ultoa" name="ultoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>bgcolor<label id="bgcolor"><p> + +<quote> +<descrip> +<tag/Function/Set the background text color. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ bgcolor (unsigned char color);/ +<tag/Description/The function will set a new background color and return the +old (current) one. The background color is valid for the whole text output +area of the screen, not just for new text. +<tag/Limits/<itemize> +<item>Background colors are system dependent. The function may have no effect +on systems where the background color cannot be changed. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="bordercolor" name="bordercolor">, +<ref id="textcolor" name="textcolor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>bordercolor<label id="bordercolor"><p> + +<quote> +<descrip> +<tag/Function/Set the border (frame) color. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ bordercolor (unsigned char color);/ +<tag/Description/The function will set a new border color. It returns the old +(current) border color. +<tag/Limits/<itemize> +<item>Border colors are system dependent. The function may have no effect +on systems where the border color cannot be changed. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="bgcolor" name="bgcolor">, +<ref id="textcolor" name="textcolor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>bsearch<label id="bsearch"><p> + +<quote> +<descrip> +<tag/Function/Do a binary search in a sorted array. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void* __fastcall__ bsearch (const void* key, +const void* base, size_t n, size_t size, +int (*cmp) (const void*, const void*));/ +<tag/Description/<tt/bsearch/ searches a sorted array for a member that +matches the one pointed to by <tt/key/. <tt/base/ is the address of the array, +<tt/n/ is the number of elements, <tt/size/ the size of an element and <tt/cmp/ +the function used to compare the members against the key. The function returns +a pointer to the member found, or <tt/NULL/ if there was no match. +<tag/Limits/ +<itemize> +<item>The contents of the array must be sorted in ascending order according to +the compare function given. +<item>If there are multiple members that match the key, the function will +return one of the members. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="qsort" name="qsort"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>bzero<label id="bzero"><p> + +<quote> +<descrip> +<tag/Function/Fill a memory area with zeroes. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void __fastcall__ bzero (void* p, size_t count);/ +<tag/Description/<tt/bzero/ fills the memory area pointed to by <tt/p/ with +zero. +<tag/Limits/ +<itemize> +<item>The function is non standard and therefore only available in non ANSI +mode. You should use <tt/<ref id="memset" name="memset">/ instead. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="_swap" name="_swap">, +<ref id="memcpy" name="memcpy">, +<ref id="memmove" name="memmove">, +<ref id="memset" name="memset">, +<tag/Example/None. +</descrip> +</quote> + + +<sect1>c64mode<label id="c64mode"><p> + +<quote> +<descrip> +<tag/Function/Switch the C128 into C64 compatible mode. +<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/void c64mode (void);/ +<tag/Description/The function will cause the machine to reboot into C64 mode. +<tag/Limits/<itemize> +<item>The function is specific to the C128. +<item>The function will not return to the caller. +</itemize> +<tag/Availability/C128 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>calloc<label id="calloc"><p> + +<quote> +<descrip> +<tag/Function/Allocate and clear memory. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void* __fastcall__ calloc (size_t n, size_t size);/ +<tag/Description/<tt/calloc/ allocates memory for an array of <tt/n/ elements +of size <tt/size/, clears the whole block with binary zeroes and returns a +pointer to it. On error (not enough memory available), <tt/calloc/ returns +<tt/NULL/. +<tag/Limits/ +<itemize> +<item>Clearing the memory may not have the expected effect on all platforms: +pointers in the block may not be <tt/NULL/ and floating point variables may +not be zero (0.0). In other words: The "clearing" effect of this function +should be used with care for portable programs. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="free" name="free">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_acptr<label id="cbm_k_acptr"><p> + +<quote> +<descrip> +<tag/Function/Input byte from serial bus +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_acptr (void);/ +<tag/Description/The function returns a byte of data, which it +gets from the current TALKer on the serial bus. +In order to receive the data, the device must have previously been +sent a command to TALK and a secondary address if it needs one. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_talk" name="cbm_k_talk">, +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_basin<label id="cbm_k_basin"><p> + +<quote> +<descrip> +<tag/Function/Input a Character from the Current Device +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_basin (void);/ +<tag/Description/The function returns a character from the current input device. +Device must first have been OPENed and then designated as the input channel by the CHKIN routine. +When this function is called, the next byte of data available from the device is returned. +Exception is the routine for the keyboard device (which is the default input device). +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_chkin" name="cbm_k_chkin"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_bsout<label id="cbm_k_bsout"><p> + +<quote> +<descrip> +<tag/Function/Output a byte +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_bsout (unsigned char C);/ +<tag/Description/Function sends the character to the current output device. +Unless a device has been OPENed and designated as the +current output channel using the CHKOUT routine, the character is +printed to the screen, which is the default output device. If the +cassette is the current device, outputting a byte will only add it to +the buffer. No actual transmission of data will occur until the +192-byte buffer is full. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_chkin" name="cbm_k_chkout"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_chkin<label id="cbm_k_chkin"><p> + +<quote> +<descrip> +<tag/Function/Designate a Logical File As the Current Input Channel +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_chkin (unsigned char FN);/ +<tag/Description/If you wish to +get data from any device other than the keyboard, this function must be +called after OPENing the device, before you can get a data byte with +the cbm_k_basin or cbm_k_getin routine. When called, the routine will designate +the logical file whose file number was supplied as the +current file, its device as the current device, and its secondary +address as the current secondary address. If the device on the +channel is a serial device, which requires a TALK command and +sometimes a secondary address, function will send them over the +serial bus. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_basin" name="cbm_k_basin">, +<ref id="cbm_k_getin" name="cbm_k_getin"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_ciout<label id="cbm_k_ciout"><p> + +<quote> +<descrip> +<tag/Function/Transmit a byte over the serial bus +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_ciout (unsigned char C);/ +<tag/Description/Purpose of this function is to send a byte of data over +the serial bus. In order for the data to be received, the serial +device must have first been commanded to LISTEN and been given a +secondary address if necessary. This routine always buffers the +current character, and defers sending it until the next byte is +buffered. When the UNLISTEN command is sent, the last byte will be +sent with an End or Identify (EOI). +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_listen" name="cbm_k_listen">, +<ref id="cbm_k_unlsn" name="cbm_k_unlsn"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_ckout<label id="cbm_k_ckout"><p> + +<quote> +<descrip> +<tag/Function/Designate a Logical File As the Current Output Channel +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_ckout (unsigned char FN);/ +<tag/Description/If you wish to +output data to any device other than the screen, this routine must be +called after OPENing the device, and before you output a data byte +with the cbm_k_bsout() function. When called, the function will designate the +logical file whose file number was supplied as the current +file, its device as the current device, and its secondary address as +the current secondary address. If the device on the channel uses the +serial bus, and therefore requires a LISTEN command and possibly a +secondary address, this information will be sent on the bus. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_bsout" name="cbm_k_bsout">, +<ref id="cbm_k_listen" name="cbm_k_listen"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_clall<label id="cbm_k_clall"><p> + +<quote> +<descrip> +<tag/Function/Close All Logical I/O Files +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void cbm_k_clall (void);/ +<tag/Description/It closes all +open files, by resetting the index into open files to +zero and restores the default I/O devices. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_close" name="cbm_k_close"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_close<label id="cbm_k_close"><p> + +<quote> +<descrip> +<tag/Function/Close a Logical I/O File +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_close (unsigned char FN);/ +<tag/Description/It is used to +close a logical file after all I/O operations involving that file have +been completed. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_clall" name="cbm_k_clall"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_clrch<label id="cbm_k_clrch"><p> + +<quote> +<descrip> +<tag/Function/Restore Current Input and Output Devices to the Default Devices +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void cbm_k_clrch (void);/ +<tag/Description/It sets the +current input device to the keyboard, and the current output device to +the screen. Also, if the current input device was formerly a serial +device, the routine sends it an UNTALK command on the serial bus, and +if a serial device was formerly the current output device, the routine +sends it an UNLISTEN command. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_chkin" name="cbm_k_chkin">, +<ref id="cbm_k_ckout" name="cbm_k_ckout"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_getin<label id="cbm_k_getin"><p> + +<quote> +<descrip> +<tag/Function/Get One Byte from the Input Device +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_getin (void);/ +<tag/Description/Function gets a character from the current input device. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_basin" name="cbm_k_basin"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_iobase<label id="cbm_k_iobase"><p> + +<quote> +<descrip> +<tag/Function/Return Base Address of Memory-Mapped I/O Devices +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned cbm_k_iobase (void);/ +<tag/Description/This function returns the address of +the memory section where the memory mapped I/O devices are located. This +address can then be used with an offset to access the memory mapped I/O +devices in the Commodore 64. The offset is the number of locations from +the beginning of the page on which the I/O register you want is located. +This function exists to provide compatibility between the Commodore 64, +VIC-20, and future models of the Commodore 64. If the I/O locations for +a program are set by a call to this function, they should +still remain compatible with future versions of the Commodore 64, the +KERNAL and BASIC. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ + +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_listen<label id="cbm_k_listen"><p> + +<quote> +<descrip> +<tag/Function/Command a device on the serial bus to LISTEN +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_listen (unsigned char dev);/ +<tag/Description/This function will command a device on the serial bus to +receive data. The KERNAL routine will OR the supplied device number bit by bit +to convert it to a listen address, then transmits this data as a command on +the serial bus. The specified device will then go into listen mode, and +be ready to accept information. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_unlsn" name="cbm_k_unlsn">, +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_load<label id="cbm_k_load"><p> + +<quote> +<descrip> +<tag/Function/Load RAM from a Device +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned int __fastcall__ cbm_k_load(unsigned char flag, unsigned addr);/ +<tag/Description/This function LOADs data bytes from any input device directly into the memory. +It can also be used for a verify operation, comparing data from a device with the data already in +memory, while leaving the data stored in RAM unchanged. +The flag must be set to 0 for a LOAD operation, or 1 for a +verify, If the input device is OPENed with a secondary address (SA) of 0 +the header information from the device is ignored. In this case, the starting address for the load must be supplied. +If the device is addressed with a secondary address of 1, then the data is +loaded into memory starting at the location specified by the header. +Function returns the address of the highest RAM location loaded. +Before this function can be called, the KERNAL SETLFS, and SETNAM +routines must be called. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_save" name="cbm_k_save">, +<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, +<ref id="cbm_k_setnam" name="cbm_k_setnam"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_open<label id="cbm_k_open"><p> + +<quote> +<descrip> +<tag/Function/Open a Logical I/O File +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_open (void);/ +<tag/Description/This function assigns a logical file to a device, so that it can be used for +Input/Output operations. In order to specify the logical file number, +the device number, and the secondary address if any, the cbm_k_setlfs() function must first be called. +Likewise, in order to designate the filename, the cbm_k_setnam() function must be used first. After these two +functions are called, cbm_k_open() is then called. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_close" name="cbm_k_close">, +<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, +<ref id="cbm_k_setnam" name="cbm_k_setnam"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_readst<label id="cbm_k_readst"><p> + +<quote> +<descrip> +<tag/Function/Read status word +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char cbm_k_readst (void);/ +<tag/Description/This function returns the current status of the I/O devices. It is usually called after new communication to an I/O device and gives information about device status, or errors that have occurred during the I/O operation. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ + +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_save<label id="cbm_k_save"><p> + +<quote> +<descrip> +<tag/Function/Save RAM to a Device +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_save(unsigned int start, unsigned int end)/ +<tag/Description/This function saves a section of memory. The cbm_k_setlfs() and cbm_k_setnam() functions must be +used before calling this function. However, a file name is not required to +SAVE to device 1 (the Datassette(TM) recorder). Any attempt to save to +other devices without using a file name results in an error. NOTE: Device 0 (the keyboard), device 2 (RS-232), and device 3 (the screen) cannot be SAVEd to. If the attempt is made, an error occurs, and the SAVE is stopped. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_load" name="cbm_k_load">, +<ref id="cbm_k_setlfs" name="cbm_k_setlfs">, +<ref id="cbm_k_setnam" name="cbm_k_setnam"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_setlfs<label id="cbm_k_setlfs"><p> + +<quote> +<descrip> +<tag/Function/Set up a logical file +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_setlfs (unsigned char LFN, unsigned char DEV, unsigned char SA);/ +<tag/Description/This functions sets up the logical file by setting its number, device address, +and secondary address. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_setnam" name="cbm_k_setnam"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_setnam<label id="cbm_k_setnam"><p> + +<quote> +<descrip> +<tag/Function/Set Filename Parameters +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_setnam (const char* Name);/ +<tag/Description/This function is used to set up the file name for the OPEN, +SAVE, or LOAD operations. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_open" name="cbm_k_open">, +<ref id="cbm_k_load" name="cbm_k_load">, +<ref id="cbm_k_save" name="cbm_k_save"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_talk<label id="cbm_k_talk"><p> + +<quote> +<descrip> +<tag/Function/Commands device to TALK +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void __fastcall__ cbm_k_talk (unsigned char dev);/ +<tag/Description/When called, it ORs the device number with the TALK code (64, $40) and sends it on the serial +bus. This commands the device to TALK. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_acptr" name="cbm_k_acptr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cbm_k_unlsn<label id="cbm_k_unlsn"><p> + +<quote> +<descrip> +<tag/Function/Send an UNLISTEN command +<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/ +<tag/Declaration/<tt/void cbm_k_unlsn (void);/ +<tag/Description/This function commands all devices on the serial bus to +stop receiving data from the host computer (i.e., UNLISTEN). Calling this +function results in an UNLISTEN command being transmitted on the serial +bus. Only devices previously commanded to LISTEN are affected. This +function is normally used after the host computer is finished sending data +to external devices. Sending the UNLISTEN commands the listening devices +to get off the serial bus so it can be used for other purposes. +<tag/Limits/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cbm_k_listen" name="cbm_k_listen"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cclear<label id="cclear"><p> + +<quote> +<descrip> +<tag/Function/Clear part of a line (write a given number of spaces). +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cclear (unsigned char length);/ +<tag/Description/The function clears part of a line by writing <tt/length/ +spaces in the current text color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cclearxy" name="cclearxy">, +<ref id="clrscr" name="clrscr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cclearxy<label id="cclearxy"><p> + +<quote> +<descrip> +<tag/Function/Clear part of a line (write a given number of spaces) starting +at a specific screen position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cclearxy (unsigned char x, unsigned char y, unsigned char length);/ +<tag/Description/The function moves the cursor to a specific position, and +will then clear part of the line by writing <tt/length/ spaces in the current +text color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cclear" name="cclear">, +<ref id="clrscr" name="clrscr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cgetc<label id="cgetc"><p> + +<quote> +<descrip> +<tag/Function/Read a character from the keyboard. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/char cgetc (void);/ +<tag/Description/The function reads a character from the keyboard. If there is +no character available, <tt/cgetc/ waits until the user presses a key. If the +cursor is enabled by use of the <tt/cursor/ function, a blinking cursor is +displayed while waiting. +<tag/Limits/<itemize> +<item>If the system supports a keyboard buffer, <tt/cgetc/ will fetch a key +from this buffer and wait only if the buffer is empty. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cursor" name="cursor">, +<ref id="kbhit" name="kbhit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>chline<label id="chline"><p> + +<quote> +<descrip> +<tag/Function/Output a horizontal line in text mode. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ chline (unsigned char length);/ +<tag/Description/The function outputs a horizontal line with the given length +starting at the current cursor position. +<tag/Limits/<itemize> +<item>The character used to draw the horizontal line is system dependent. +If available, a line drawing character is used. Drawing a line that is partially +off screen leads to undefined behaviour. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="chlinexy" name="chlinexy">, +<ref id="cvline" name="cvline">, +<ref id="cvlinexy" name="cvlinexy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>chlinexy<label id="chlinexy"><p> + +<quote> +<descrip> +<tag/Function/Output a horizontal line at a given position in text mode. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ chlinexy (unsigned char x, unsigned char y, unsigned char length);/ +<tag/Description/The function outputs a horizontal line with the given length +starting at a given position. +<tag/Limits/<itemize> +<item>The character used to draw the horizontal line is system dependent. +If available, a line drawing character is used. Drawing a line that is partially +off screen leads to undefined behaviour. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="chline" name="chline">, +<ref id="cvline" name="cvline">, +<ref id="cvlinexy" name="cvlinexy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>clearerr<label id="clearerr"><p> + +<quote> +<descrip> +<tag/Function/Clear error and end-of-file status of a stream. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/void __fastcall__ clearerr (FILE* f);/ +<tag/Description/<tt/clearerr/ clears the error and end-of-file status +indicators for the stream <tt/f/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="feof" name="feof">, +<ref id="ferror" name="ferror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>clock<label id="clock"><p> + +<quote> +<descrip> +<tag/Function/Determine the processor time used. +<tag/Header/<tt/<ref id="time.h" name="time.h">/ +<tag/Declaration/<tt/clock_t clock (void);/ +<tag/Description/The <tt/clock/ function returns an approximaton of processor +time used by the program. The time is returned in implementation defined +units. It can be converted to seconds by dividing by the value of the macro +<tt/CLOCKS_PER_SEC/. +<tag/Limits/<itemize> +<item>Since the machines, cc65 generated programs run on, cannot run multiple +processes, the function will actually return the time since some +implementation defined point in the past. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="time" name="time"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>clrscr<label id="clrscr"><p> + +<quote> +<descrip> +<tag/Function/Clear the text screen. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void clrscr (void);/ +<tag/Description/The function clears the text screen and moves the cursor to +the upper left corner. +<tag/Availability/cc65 +<tag/See also/ +<ref id="cclear" name="cclear">, +<ref id="cclearxy" name="cclearxy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>close<label id="close"><p> + +<quote> +<descrip> +<tag/Function/Close a file descriptor. +<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ +<tag/Declaration/<tt/int __fastcall__ close (int fd);/ +<tag/Description/The function closes the given file descriptor. It returns zero +on success and -1 on error. If an error occurs, the cause can be determined by +reading the <tt/errno/ variable. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="creat" name="creat">, +<ref id="open" name="open"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>closedir<label id="closedir"><p> + +<quote> +<descrip> +<tag/Function/Close a directory. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/int __fastcall__ closedir (DIR* dir);/ +<tag/Description/The function closes the given directory descriptor. It returns +zero on success and -1 on error. If an error occurs, the cause can be determined +by reading the <tt/errno/ variable. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="opendir" name="opendir">, +<ref id="readdir" name="readdir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>creat<label id="creat"><p> + +<quote> +<descrip> +<tag/Function/Create a file. +<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ +<tag/Declaration/<tt/int __fastcall__ creat (const char* name, unsigned mode);/ +<tag/Description/<tt/creat/ creates a new file and returns the file descriptor +associated with it. On error, -1 is returned and an error code is stored in +<tt/errno/. +<tag/Limits/<itemize> +<item><tt/creat/ is identical to calling <tt/<ref id="open" name="open">/ with +<tt/flags/ equal to <tt/O_WRONLY | O_CREAT | O_TRUNC/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="close" name="close">, +<ref id="open" name="open"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cprintf<label id="cprintf"><p> + +<quote> +<descrip> +<tag/Function/Formatted output to the console. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/int cprintf (const char* format, ...);/ +<tag/Description/The arguments are converted to text where necessary and +formatted according to the format string given. The resulting string is output +to the console. <tt/cprintf/ supports the same format specifiers as +<tt/printf/. <!-- <tt/<ref id="printf" name="printf">/. --> +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cprintf/ distinguishes +between <tt/\r/ and <tt/\n/. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cputc" name="cputc">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputs" name="cputs">, +<ref id="cputsxy" name="cputsxy">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cputc<label id="cputc"><p> + +<quote> +<descrip> +<tag/Function/Output a character directly to the console. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cputc (char c);/ +<tag/Description/Output one character to the console at the current cursor +position. +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cputc/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputs" name="cputs">, +<ref id="cputsxy" name="cputsxy">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cputcxy<label id="cputcxy"><p> + +<quote> +<descrip> +<tag/Function/Output a character at a specific screen position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cputcxy (unsigned char x, unsigned char y, char c);/ +<tag/Description/<tt/cputcxy/ moves the cursor to the given x/y position on +the screen and outputs one character. +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cputcxy/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputc" name="cputc">, +<ref id="cputs" name="cputs">, +<ref id="cputsxy" name="cputsxy">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cputs<label id="cputs"><p> + +<quote> +<descrip> +<tag/Function/Output a string directly to the console. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cputs (const char* s);/ +<tag/Description/The function outputs the given string on the console at the +current cursor position. +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cputs/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputc" name="cputc">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputsxy" name="cputsxy">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cputsxy<label id="cputsxy"><p> + +<quote> +<descrip> +<tag/Function/Output a string to the console at a given position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cputsxy (unsigned char x, unsigned char y, const char* s);/ +<tag/Description/<tt/cputsxy/ moves the cursor to the given x/y position, +and outputs the string <tt/s/. +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/cputsxy/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputc" name="cputc">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputs" name="cputs">, +<ref id="vcprintf" name="vcprintf"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cursor<label id="cursor"><p> + +<quote> +<descrip> +<tag/Function/Enable/disable a blinking cursor when waiting for keyboard input. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ cursor (unsigned char onoff);/ +<tag/Description/If the argument to the function is non zero, a blinking cursor +will be enabled when the <tt/cgetc/ function waits for input from the keyboard. +If the argument is zero, <tt/cgetc/ will wait without a blinking cursor. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cgetc" name="cgetc">, +<ref id="kbhit" name="kbhit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cvline<label id="cvline"><p> + +<quote> +<descrip> +<tag/Function/Output a vertical line in text mode. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cvline (unsigned char length);/ +<tag/Description/The function outputs a vertical line with the given length +starting at the current cursor position. +<tag/Limits/<itemize> +<item>The character used to draw the vertical line is system dependent. +If available, a line drawing character is used. Drawing a line that is partially +off screen leads to undefined behaviour. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="chline" name="chline">, +<ref id="chlinexy" name="chlinexy">, +<ref id="cvlinexy" name="cvlinexy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>cvlinexy<label id="cvlinexy"><p> + +<quote> +<descrip> +<tag/Function/Output a vertical line at a given position in text mode. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ cvlinexy (unsigned char x, unsigned char y, unsigned char length);/ +<tag/Description/The function outputs a vertical line with the given length +starting at a given position. +<tag/Limits/<itemize> +<item>The character used to draw the vertical line is system dependent. +If available, a line drawing character is used. Drawing a line that is partially +off screen leads to undefined behaviour. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="chline" name="chline">, +<ref id="chlinexy" name="chlinexy">, +<ref id="cvline" name="cvline"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>div<label id="div"><p> + +<quote> +<descrip> +<tag/Function/Divide two ints and return quotient and remainder. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/div_t __fastcall__ div (int numer, int denom);/ +<tag/Description/<tt/div/ divides <tt/numer/ by <tt/denom/ and returns the +quotient and remainder in a <tt/div_t/ structure. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +ldiv +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_commit<label id="em_commit"><p> + +<quote> +<descrip> +<tag/Function/Commit changes into extended memory. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void em_commit (void);/ +<tag/Description/Commit changes in the memory window to extended storage. If +the contents of the memory window have been changed, these changes may be lost +if <tt/<ref id="em_map" name="em_map">/, <tt/<ref id="em_use" name="em_use">/, +<tt/<ref id="em_copyfrom" name="em_copyfrom">/ or <tt/<ref id="em_copyto" +name="em_copyto">/ are called without calling <tt/em_commit/ first. +<tag/Limits/<itemize> +<item>Calling <tt/em_commit/ does not necessarily mean that changes to the +memory window are discarded, it does just mean that the drivers is allowed +to discard it. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_map" name="em_map">, +<ref id="em_use" name="em_use"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_copyfrom<label id="em_copyfrom"><p> + +<quote> +<descrip> +<tag/Function/Copy from extended into normal memory. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void __fastcall__ em_copyfrom (const struct em_copy* copy_data);/ +<tag/Description/Copy data from extended memory into linear memory. Source and +target addresses as well as the number of bytes to transfer are specified in +the <tt/em_copy/ structure that is passed as a parameter. +<tag/Limits/<itemize> +<item>Calling <tt/em_copyfrom/ will invalidate the memory window, so if you +made any changes to the data in the window, call <tt/<ref id="em_commit" +name="em_commit">/ first, or the changes are lost. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_commit" name="em_commit">, +<ref id="em_copyto" name="em_copyto">, +<ref id="em_load_driver" name="em_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_copyto<label id="em_copyto"><p> + +<quote> +<descrip> +<tag/Function/Copy from normal into extended memory. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void __fastcall__ em_copyto (const struct em_copy* copy_data);/ +<tag/Description/Copy data from linear into extended memory. Source and +target addresses as well as the number of bytes to transfer are specified in +the <tt/em_copy/ structure that is passed as a parameter. +<tag/Limits/<itemize> +<item>Calling <tt/em_copyto/ will invalidate the memory window, so if you +made any changes to the data in the window, call <tt/<ref id="em_commit" +name="em_commit">/ first, or the changes are lost. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_commit" name="em_commit">, +<ref id="em_copyfrom" name="em_copyfrom">, +<ref id="em_load_driver" name="em_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_install<label id="em_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded extended memory driver. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/unsigned char _fastcall__ em_install (void* driver);/ +<tag/Description/The function installs an already loaded extended memory driver +and returns an error code. The function may be used to install a driver linked +statically to the program. +<tag/Limits/<itemize> +<item>Not all drivers are able to detect if the supported hardware is really +present. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_uninstall" name="em_uninstall">, +<ref id="em_unload" name="em_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_load_driver<label id="em_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load and initialize an extended memory driver. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void __fastcall__ em_load_driver (const char* name);/ +<tag/Description/Load an extended memory driver into memory and initialize +it. The function returns an error code that tells if all this has been +successful. +<tag/Limits/<itemize> +<item>Not all drivers are able to detect if the supported hardware is really +present. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The driver is loaded by name, so currently you must know the type of +extended memory that should be supported. There is no autodetect capability. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_unload" name="em_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_map<label id="em_map"><p> + +<quote> +<descrip> +<tag/Function/Make a page of extended memory accessible. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void* __fastcall__ em_map (unsigned page);/ +<tag/Description/The function maps one page of extended memory into linear +memory and returns a pointer to the page frame. Depending on the hardware +and driver, the data is either mapped into the address space or transfered +into a buffer. If you don't need the actual contents of the page (for example +because you're going to overwrite it completely), it is better to call +<tt/<ref id="em_use" name="em_use">/ instead. <tt/em_use/ will not transfer the +data if it is possible to avoid that. +<tag/Limits/<itemize> +<item>Calling <tt/em_map/ will invalidate the memory window, so if you +made any changes to the data in the window, call <tt/<ref id="em_commit" +name="em_commit">/ first, or the changes are lost. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_commit" name="em_commit">, +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_use" name="em_use"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_pagecount<label id="em_pagecount"><p> + +<quote> +<descrip> +<tag/Function/Return the number of available extended memory pages. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/unsigned em_pagecount (void);/ +<tag/Description/The function returns the size of the extended memory supported +by the driver in 256 byte pages. +<tag/Limits/<itemize> +<item>The function returns zero if no extended memory driver is loaded. +<item>The function may return zero if the supported hardware was not detected. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_load_driver" name="em_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_uninstall<label id="em_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall an already loaded extended memory driver. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/unsigned char em_uninstall (void);/ +<tag/Description/The function uninstalls an already loaded extended memory +driver but doesn't remove it from memory. +<tag/Limits/<itemize> +<item>If the driver has been loaded using <tt/<ref id="em_load_driver" +name="em_load_driver">/, <tt/<ref id="em_unload" name="em_unload">/ +should be used instead of <tt/em_uninstall/ so the driver is also removed +from memory. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_install" name="em_install">, +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_unload" name="em_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_unload<label id="em_unload"><p> + +<quote> +<descrip> +<tag/Function/Unload an extended memory driver. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/unsigned char em_unload (void);/ +<tag/Description/The function unloads a loaded extended memory driver and +frees all memory allocated for the driver. +<tag/Limits/<itemize> +<item>The function does nothing if no driver is loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_load_driver" name="em_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>em_use<label id="em_use"><p> + +<quote> +<descrip> +<tag/Function/Prepare an extended memory page for use. +<tag/Header/<tt/<ref id="em.h" name="em.h">/ +<tag/Declaration/<tt/void* __fastcall__ em_use (unsigned page);/ +<tag/Description/The function maps one page of extended memory into linear +memory and returns a pointer to the page frame. This function is similar to +<tt/<ref id="em_map" name="em_map">/, but will not transfer data into the +actual memory window in the assumption that the existing data is wrong or +will get overwritten. +<tag/Limits/<itemize> +<item>Calling <tt/em_use/ will invalidate the memory window, so if you +made any changes to the data in the window, call <tt/<ref id="em_commit" +name="em_commit">/ first, or the changes are lost. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>The function produces undefined results if no extended memory driver is +loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="em_commit" name="em_commit">, +<ref id="em_load_driver" name="em_load_driver">, +<ref id="em_map" name="em_map"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>exit<label id="exit"><p> + +<quote> +<descrip> +<tag/Function/Terminate the program. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ exit (int status);/ +<tag/Description/<tt/exit/ terminates the program. The argument specifies the +return code of the program. Before termination, all files are closed, buffered +output is written and any functions registered with <tt/<ref id="atexit" +name="atexit">/ are called. Common values for status are <tt/EXIT_SUCCESS/ and +<tt/EXIT_FAILURE/ which are also defined in <tt/<ref id="stdlib.h" +name="stdlib.h">/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>It depends on the host machine if the program return code can be +evaluated or is ignored. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="exit" name="exit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>exec<label id="exec"><p> + +<quote> +<descrip> +<tag/Function/Execute a program file. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/int __fastcall__ exec (const char* progname, const char* cmdline);/ +<tag/Description/<tt/exec/ replaces the currently running program by a new one. +Calling <tt/exec()/ is identical to calling <tt/<ref id="exit" name="exit()">/, +then loading and starting the program named in the first argument, passing +the command line specified as second argument. Instead of an empty string, +a <tt/NULL/ pointer may be passed as second parameter. +On success, the function does not return. On failure, -1 is returned and +<tt/errno/ contains an error code. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>On most platforms, the function needs to copy a small stub loader to +some memory area outside the program space. This may collide with other +programs. See the platform specific docs on this. +<item>Because it is necessary to terminate the running program before the +memory can be reused to load the new one, there is a high chance that the +function may not be able to return on errors. +<item>The command line is passed to the new program in the same way as cc65 +programs expect the command line. If the new program is not a cc65 generated +program, it may not be able to read it. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="exit" name="exit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>fast<label id="fast"><p> + +<quote> +<descrip> +<tag/Function/Switch the C128 into 2MHz mode. +<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/void fast (void);/ +<tag/Description/The function will switch the clock of the C128 to 2MHz. This +will nearly double the speed compared to slow mode. +<tag/Limits/<itemize> +<item>The function is specific to the C128. +<item>2MHz clock will not work in 40 column mode. +</itemize> +<tag/Availability/C128 +<tag/See also/ +<ref id="slow" name="slow">, +<ref id="toggle_videomode" name="toggle_videomode">, +<ref id="videomode" name="videomode"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>feof<label id="feof"><p> + +<quote> +<descrip> +<tag/Function/Return the end-of-file indicator of a stream. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ feof (FILE* f);/ +<tag/Description/<tt/feof/ tests the end-of-file indicator ofthe stream +<tt/f/, and returns a non zero value if it is set. +<tag/Limits/<itemize> +<item>The indicator is set only after a read past the end of a file is +attempted. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="feof" name="clearerr">, +<ref id="ferror" name="ferror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ferror<label id="ferror"><p> + +<quote> +<descrip> +<tag/Function/Return the error indicator of a stream. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ ferror (FILE* f);/ +<tag/Description/<tt/ferror/ tests the error indicator of the stream +<tt/f/, and returns a non zero value if it is set. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="feof" name="clearerr">, +<ref id="ferror" name="feof"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>fileno<label id="fileno"><p> + +<quote> +<descrip> +<tag/Function/Return the file handle used by a stream. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ fileno (FILE* f);/ +<tag/Description/The <tt/fileno/ function returns the file handle used +internally by a C stream. This file handle (an integer) can be used as a +handle for the POSIX input/output functions. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>Mixing C file I/O functions and POSIX file I/O functions for the same +file may have unpredictable results. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="creat" name="creat">, +<ref id="open" name="open"> <!-- , --> +<!-- <ref id="read" name="read">, --> +<!-- <ref id="write" name="write"> --> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>free<label id="free"><p> + +<quote> +<descrip> +<tag/Function/Free a block of dynamic memory. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ free (void* block);/ +<tag/Description/Free a block of dynamic memory previously allocated with +<tt/<ref id="malloc" name="malloc">/, <tt/<ref id="calloc" name="calloc">/ +or <tt/<ref id="realloc" name="realloc">/. As an exception, if the passed +pointer is <tt/NULL/, no action is performed. +<tag/Limits/ +<itemize> +<item>Passing an already free'd block to <tt/free/ again will cause undefined +behaviour and may crash your program. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="malloc" name="malloc">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>get_ostype<label id="get_ostype"><p> + +<quote> +<descrip> +<tag/Function/The function returns the operating system, the program runs on. +<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">, +<ref id="atari.h" name="atari.h">, <ref id="c64.h" name="c64.h">/ +<tag/Declaration/<tt/unsigned char get_ostype (void);/ +<tag/Description/<tt/get_ostype/ is machine dependent and does not exist for +all supported targets. If it exists, it returns a number that identifies the +operating system or machine type, the program runs on. The machine dependent +header files define constants that can be used to check the return code. +<tag/Limits/<itemize> +<item>The function does not exist on all platforms. +<item>The return codes are platform dependent. +</itemize> +<tag/Availability/cc65 (not all platforms) +<tag/Example/None. +</descrip> +</quote> + + +<sect1>getcpu<label id="getcpu"><p> + +<quote> +<descrip> +<tag/Function/Determine on which CPU the program is running. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/unsigned char getcpu (void);/ +<tag/Description/The function checks on which CPU the code is running. It +returns one of the constants<itemize> +<item><tt/CPU_6502/ +<item><tt/CPU_65C02/ +<item><tt/CPU_65816/ +</itemize> +<tag/Limits/<itemize> +<item>Other, more exotic CPU types are not disinguished. +</itemize> +<tag/Availability/cc65 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>getenv<label id="getenv"><p> + +<quote> +<descrip> +<tag/Function/Return a value from the environment. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ getenv (const char* name);/ +<tag/Description/The function searches the environment for an entry that +matches <tt/name/ and returns its value. The environment consists of a list +of strings in the form <tt/name=value/. If there is no match, <tt/getenv/ +returns <tt/NULL/. +<tag/Limits/<itemize> +<item>What exactly is stored in the environment depends on the machine the +program is running on. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>getopt<label id="getopt"><p> + +<quote> +<descrip> +<tag/Function/Parse command line options. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/int __fastcall__ getopt (int argc, char* const* argv, +const char* optstring);/ +<tag/Description/The function parses command line arguments, <tt/argc/ and +<tt/argv/ are the argument count and array passed to <tt/main/. <tt/optstring/ +is a string that contains command line option characters. If a character in +<tt/optstring/ is followed by a colon, the option requires an argument. An +option on the command line is recognized if it is one of the option characters +preceeded by a '-'. +<tt/getopt/ must be called repeatedly. It will return each option character +found on the command line and <tt/EOF/ (-1) if there is no other option. An +option argument is placed in <tt/optarg/, the index of the next element on the +command line to be processed is placed in <tt/optind/. +<tag/Limits/<itemize> +<item>The implementation will not reorder options. A non option on the command +line will terminate option processing. All remaining arguments are not +recognized as options, even if the start with a '-' character. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX.2 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>gotox<label id="gotox"><p> + +<quote> +<descrip> +<tag/Function/Move the text mode cursor to a new X position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ gotox (unsigned char x);/ +<tag/Description/The function moves the text mode cursor to the specified X +position while leaving the Y position untouched. The leftmost position on the +screen has the coordinate 0. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +<item>Invalid values for the X position (out of screen coordinates) may +lead to undefined behaviour. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotoy" name="gotoy">, +<ref id="gotoxy" name="gotoxy">, +<ref id="wherex" name="wherex">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>gotoxy<label id="gotoxy"><p> + +<quote> +<descrip> +<tag/Function/Move the text mode cursor to a new position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ gotoxy (unsigned char x, unsigned char y);/ +<tag/Description/The function moves the text mode cursor to the specified +position. The leftmost position on the screen has the X coordinate 0, the +topmost line has the Y coordinate 0. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +<item>Invalid values for any of both coordinates (out of screen positions) may +lead to undefined behaviour. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoy" name="gotoy">, +<ref id="wherex" name="wherex">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>gotoy<label id="gotoy"><p> + +<quote> +<descrip> +<tag/Function/Move the text mode cursor to a new Y position. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ gotoy (unsigned char x);/ +<tag/Description/The function moves the text mode cursor to the specified Y +position while leaving the X position untouched. The uppermost position on the +screen has the coordinate 0. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +<item>Invalid values for the Y position (out of screen coordinates) may lead +to undefined behaviour. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoxy" name="gotoxy">, +<ref id="wherex" name="wherex">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isalnum<label id="isalnum"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a letter or digit. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isalnum (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a letter or digit. The return value is zero if the character is anything +else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing +the macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isalpha<label id="isalpha"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a letter. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isalpha (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a letter. The return value is zero if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isascii<label id="isascii"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is in the ASCII (0..127) range. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isascii (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is in the range 0..127 (the range of valid ASCII characters) and zero if not. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isblank<label id="isblank"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a space or tab. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isblank (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a space or tab character. The return value is zero if the character is +anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>iscntrl<label id="iscntrl"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a control character. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ iscntrl (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a control character. The return value is zero if the character is anything +else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isdigit<label id="isdigit"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a digit. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isdigit (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a digit. The return value is zero if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isgraph<label id="isgraph"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a printable character (except +space). +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isgraph (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a printable character with the exception of space. The return value is zero +if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>islower<label id="islower"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a lower case letter. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ islower (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a lower case letter. The return value is zero if the character is anything +else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isprint<label id="isprint"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a printable character. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isprint (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a printable character (this includes the space character). The return value +is zero if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ispunct<label id="ispunct"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a printable character but not a +space or an alphanumeric character. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ ispunct (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a printable character, but not a space or anything alphanumeric. The return +value is zero if the character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isspace<label id="isspace"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a a white-space character. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isspace (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a white space character. The return value is zero if the character is +anything else. The standard white space characters are: space, formfeed ('\f'), +newline ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab +('\v'). +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isupper" name="isupper">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isupper<label id="isupper"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is an upper case letter. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isupper (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is an upper case letter. The return value is zero if the character is anything +else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isxdigit" name="isxdigit"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>isxdigit<label id="isxdigit"><p> + +<quote> +<descrip> +<tag/Function/Check if a given character is a hexadecimal digit. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ isxdigit (int c);/ +<tag/Description/The function returns a non zero value if the given argument +is a hexadecimal digit (0..9, a..f and A..F). The return value is zero if the +character is anything else. +<tag/Limits/<itemize> +<item>When compiling with <tt/-Os/ the function is actually a macro. The +inline sequence generated by the macro will not work correctly for values +outside the range 0..255. <bf/Note:/ The constant <tt/EOF/ is not part of +this range. The non inline function may be accessed by <tt/#undef/'ing the +macro. +<item>When compiling without <tt/-Os/, the function is only available as +fastcall function, so it may only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="isalnum" name="isalnum">, +<ref id="isalpha" name="isalpha">, +<ref id="isascii" name="isascii">, +<ref id="isblank" name="isblank">, +<ref id="iscntrl" name="iscntrl">, +<ref id="isdigit" name="isdigit">, +<ref id="isgraph" name="isgraph">, +<ref id="islower" name="islower">, +<ref id="isprint" name="isprint">, +<ref id="ispunct" name="ispunct">, +<ref id="isspace" name="isspace">, +<ref id="isupper" name="isupper"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>itoa<label id="itoa"><p> + +<quote> +<descrip> +<tag/Function/Convert an integer into a string. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ itoa (int val, char* buf, int radix);/ +<tag/Description/<tt/itoa/ converts the integer <tt/val/ into a string using +<tt/radix/ as the base. +<tag/Limits/<itemize> +<item>There are no provisions to prevent a buffer overflow. +<item>If <tt/val/ contains <tt/INT_MIN/, the behaviour is undefined. +<item>The function is non standard, so it is not available in strict ANSI mode. +You should probably use <tt/sprintf/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="atol" name="atol">, +<ref id="ltoa" name="ltoa">, +<ref id="ultoa" name="ultoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_count<label id="joy_count"><p> + +<quote> +<descrip> +<tag/Function/Return the number of joysticks supported by the current driver. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char joy_count (void);/ +<tag/Description/The function returns a the number of joysticks supported +by the current joystick driver. +<tag/Limits/<itemize> +<item>A joystick driver must be loaded using <ref id="joy_load_driver" +name="joy_load_driver"> before calling this function. +<item>The function returns the number of joysticks supported by the driver. +There's no way to check for the number of actually connected joysticks. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_load_driver" name="joy_load_driver">, +<ref id="joy_read" name="joy_read"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_install<label id="joy_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded driver and return an error code. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ joy_install (void* driver);/ +<tag/Description/The function installs a driver that was already loaded into +memory (or linked statically to the program). It returns an error code +(<tt/JOY_ERR_OK/ in case of success). +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_load_driver" name="joy_load_driver">, +<ref id="joy_uninstall" name="joy_uninstall">, +<ref id="joy_unload" name="joy_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_load_driver<label id="joy_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load a driver from disk and install it. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ joy_load_driver (const char* driver);/ +<tag/Description/The function loads a driver with the given name from disk +and installs it. An error code is returned, which is <tt/JOY_ERR_OK/ if the +driver was successfully loaded and installed. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_install" name="joy_install">, +<ref id="joy_uninstall" name="joy_uninstall">, +<ref id="joy_unload" name="joy_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_read<label id="joy_read"><p> + +<quote> +<descrip> +<tag/Function/Read the status of a joystick. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ joy_read (unsigned char joystick);/ +<tag/Description/The function reads the status bits for a joystick. The number +of the joystick is passed as parameter. The result may be examined by using one +of the <tt/JOY_xxx/ macros from <ref id="joystick.h" name="joystick.h">. +<tag/Limits/<itemize> +<item>A joystick driver must be loaded using <ref id="joy_load_driver" +name="joy_load_driver"> before calling this function. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_count" name="joy_count">, +<ref id="joy_load_driver" name="joy_load_driver">, +<ref id="joy_unload" name="joy_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_uninstall<label id="joy_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall the current joystick driver. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char joy_uninstall (void);/ +<tag/Description/The function uninstalls the currently installed joystick +driver. It does not remove the driver from memory. The function returns an +error code, which is <tt/JOY_ERR_OK/ if the driver was successfully uninstalled. +<tag/Limits/<itemize> +<item>A joystick driver must be installed using <ref id="joy_install" +name="joy_install"> before calling this function. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_install" name="joy_install">, +<ref id="joy_load_driver" name="joy_load_driver">, +<ref id="joy_unload" name="joy_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>joy_unload<label id="joy_unload"><p> + +<quote> +<descrip> +<tag/Function/Uninstall, then unload the current joystick driver. +<tag/Header/<tt/<ref id="joystick.h" name="joystick.h">/ +<tag/Declaration/<tt/unsigned char joy_unload (void);/ +<tag/Description/The function uninstalls the currently installed joystick +driver and removes it from memory. An error code is returned, which is +<tt/JOY_ERR_OK/ if the driver was successfully uninstalled. +<tag/Limits/<itemize> +<item>A joystick driver must be loaded using <ref id="joy_load_driver" +name="joy_load_driver"> before calling this function. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="joy_load_driver" name="joy_load_driver"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>kbhit<label id="kbhit"><p> + +<quote> +<descrip> +<tag/Function/Check if there's a key waiting in the keyboard buffer. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char kbhit (void);/ +<tag/Description/The function returns a value of zero if there is no character +waiting to be read from the keyboard. It returns non zero otherwise. +<tag/Limits/<itemize> +<item>If the system does not support a keyboard buffer (most systems +do), the function is rather useless. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cgetc" name="cgetc">, +<ref id="cursor" name="cursor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>labs<label id="labs"><p> + +<quote> +<descrip> +<tag/Function/Returns the absolute value of a long integer. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/long __fastcall__ labs (long v);/ +<tag/Description/<tt/labs/ returns the absolute value of the argument passed to +the function. +<tag/Limits/<itemize> +<item>The return value is undefined if <tt/LONG_MIN/ is passed to the function. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abs" name="abs"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ltoa<label id="ltoa"><p> + +<quote> +<descrip> +<tag/Function/Convert a long integer into a string. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ ltoa (long val, char* buf, int radix);/ +<tag/Description/<tt/itoa/ converts the long integer <tt/val/ into a string +using <tt/radix/ as the base. +<tag/Limits/<itemize> +<item>There are no provisions to prevent a buffer overflow. +<item>If <tt/val/ contains <tt/LONG_MIN/, the behaviour is undefined. +<item>The function is non standard, so it is not available in strict ANSI mode. +You should probably use <tt/sprintf/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="atol" name="atol">, +<ref id="itoa" name="itoa">, +<ref id="ultoa" name="ultoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>localeconv<label id="localeconv"><p> + +<quote> +<descrip> +<tag/Function/Returns a pointer to the current locale structure. +<tag/Header/<tt/<ref id="locale.h" name="locale.h">/ +<tag/Declaration/<tt/struct lconv* localeconv (void);/ +<tag/Description/<tt/localeconv/ returns a pointer to the current locale +structure. +<tag/Limits/<itemize> +<item>cc65 supports only the "C" locale, so even after setting a new locale +using <tt/<ref id="setlocale" name="setlocale">/, the structure returned will +always be the same. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="setlocale" name="setlocale"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>longjmp<label id="longjmp"><p> + +<quote> +<descrip> +<tag/Function/Non local goto. +<tag/Header/<tt/<ref id="setjmp.h" name="setjmp.h">/ +<tag/Declaration/<tt/void __fastcall__ longjmp (jmp_buf buf, int retval);/ +<tag/Description/The <tt/longjmp/ function restores a program context from the +data in <tt/buf/, which must have been set by a preceeding call to +<tt/<ref id="setjmp" name="setjmp">/. Program execution continues as if the +call to <tt/<ref id="setjmp" name="setjmp">/ has just returned the value +<tt/retval/. +<tag/Limits/ +<itemize> +<item>If the parameter <tt/retval/ is zero, the function will behave as if it +was called with a value of one. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="setjmp" name="setjmp"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>malloc<label id="malloc"><p> + +<quote> +<descrip> +<tag/Function/Allocate dynamic memory. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void* __fastcall__ malloc (size_t size);/ +<tag/Description/<tt/malloc/ allocates size bytes on the heap and returns a +pointer to the allocated memory block. On error (not enough memory available), +<tt/malloc/ returns <tt/NULL/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="realloc" name="realloc">, +<ref id="strdup" name="strdup"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memchr<label id="memchr"><p> + +<quote> +<descrip> +<tag/Function/Search for a character in a block of raw memory. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void* __fastcall__ strchr (const void* mem, int c, size_t count);/ +<tag/Description/The <tt/memchr/ function locates the first occurrence of <tt/c/ +(converted to a char) in the block of raw memory string pointed to by <tt/mem/ +that is of size <tt/count/. Upon completion, the function returns a pointer to +the character found, or a null pointer if the character was not found. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strchr" name="strchr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memcmp<label id="memcmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two memory areas. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ memcmp (const void* p1, const void* p2, size_t count);/ +<tag/Description/<tt/memcmp/ compares <tt/count/ bytes from the memory area +pointed to by <tt/p1/ into the memory area pointed to by <tt/p2/. It returns a value that is less than +zero if <tt/p1/ is less than <tt/p2/, zero if <tt/p1/ is the same as <tt/p2/, +and a value greater than zero if <tt/p1/ is greater than <tt/p2/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcmp" name="strcmp">, +<ref id="memmove" name="memmove">, +<ref id="memset" name="memset"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memcpy<label id="memcpy"><p> + +<quote> +<descrip> +<tag/Function/Copy a memory area. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void* __fastcall__ memcpy (void* dest, const void* src, size_t count);/ +<tag/Description/<tt/memcpy/ copies <tt/count/ bytes from the memory area +pointed to by <tt/src/ into the memory area pointed to by <tt/dest/. It returns +<tt/dest/. +<tag/Limits/ +<itemize> +<item>The result is undefined if the memory areas do overlap. Use +<tt/<ref id="memmove" name="memmove">/ to copy overlapping memory areas. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_swap" name="_swap">, +<ref id="memmove" name="memmove">, +<ref id="memset" name="memset"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memmove<label id="memmove"><p> + +<quote> +<descrip> +<tag/Function/Copy a memory area. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void* __fastcall__ memmove (void* dest, const void* src, size_t count);/ +<tag/Description/<tt/memmove/ copies <tt/count/ bytes from the memory area +pointed to by <tt/src/ into the memory area pointed to by <tt/dest/. It returns +<tt/dest/. +<tag/Limits/ +<itemize> +<item>While <tt/memmove/ allows the memory areas to overlap, it has some +additional overhead compared to <tt/<ref id="memcpy" name="memcpy">/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_swap" name="_swap">, +<ref id="memcpy" name="memcpy">, +<ref id="memset" name="memset"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>memset<label id="memset"><p> + +<quote> +<descrip> +<tag/Function/Fill a memory area. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/void* __fastcall__ memset (void* p, int val, size_t count);/ +<tag/Description/<tt/memset/ fills the memory area pointed to by <tt/p/ with +the value <tt/val/. The function returns <tt/p/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_swap" name="_swap">, +<ref id="bzero" name="bzero">, +<ref id="memcpy" name="memcpy">, +<ref id="memmove" name="memmove"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mod_free<label id="mod_free"><p> + +<quote> +<descrip> +<tag/Function/Free a relocatable module. +<tag/Header/<tt/<ref id="modload.h" name="modload.h">/ +<tag/Declaration/<tt/void __fastcall__ mod_free (void* module);/ +<tag/Description/The function will free a module loaded into memory by use of +the <tt/<ref id="mod_load" name="mod_load">/ function. +<tag/Limits/<itemize> +<item>The pointer passed as parameter is the pointer to the module memory, +not the pointer to the control structure. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mod_load" name="mod_load"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mod_load<label id="mod_load"><p> + +<quote> +<descrip> +<tag/Function/Load a relocatable module. +<tag/Header/<tt/<ref id="modload.h" name="modload.h">/ +<tag/Declaration/<tt/unsigned char mod_load (struct mod_ctrl* ctrl);/ +<tag/Description/The function will load a code module into memory and relocate +it. The function will return an error code. If <tt/MLOAD_OK/ is returned, the +outgoing fields in the passed <tt/mod_ctrl/ struct contain information about +the module just loaded. Possible error codes are: +<itemize> +<item><tt/MLOAD_OK/ - Module load successful +<item><tt/MLOAD_ERR_READ/ - Read error +<item><tt/MLOAD_ERR_HDR/ - Header error +<item><tt/MLOAD_ERR_OS/ - Wrong operating system +<item><tt/MLOAD_ERR_FMT/ - Data format error +<item><tt/MLOAD_ERR_MEM/ - Not enough memory +</itemize> +<tag/Limits/<itemize> +<item>The <htmlurl url="ld65.html" name="ld65"> linker is needed to create +relocatable o65 modules for use with this function. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mod_free" name="mod_free"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_setbox<label id="mouse_setbox"><p> + +<quote> +<descrip> +<tag/Function/Specify a bounding box for the mouse cursor. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_setbox (const struct mouse_box* box);/ +<tag/Description/The function allows to set a bounding box for mouse movement. +<tag/Limits/<itemize> +<item>The function does not check if the mouse cursor is currently within the +given rectangle. Placing the mouse cursor within the bounding box is the +responsibility of the programmer. +<item>While the bounding box may be larger than the actual screen size, the +standard mouse cursor draw routines may fail to set the cursor to coordinates +outside of the screen area. Depending on the platform, you may have to supply +your own mouse cursor routines. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_getbox" name="mouse_getbox">, +<ref id="mouse_move" name="mouse_move"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_getbox<label id="mouse_getbox"><p> + +<quote> +<descrip> +<tag/Function/Return the current bounding box for the mouse cursor. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_getbox (struct mouse_box* box);/ +<tag/Description/The function queries the current bounding box for mouse +movement. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_move" name="mouse_move">, +<ref id="mouse_setbox" name="mouse_setbox"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_buttons<label id="mouse_buttons"><p> + +<quote> +<descrip> +<tag/Function/Return a bit mask encoding the state of the mouse buttons. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char mouse_buttons (void);/ +<tag/Description/The function returns a bit mask that encodes the state of the +mouse buttons. You may use the <tt/MOUSE_BTN_XXX/ flags to decode the function +return value. +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_info" name="mouse_info">, +<ref id="mouse_pos" name="mouse_pos"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_geterrormsg<label id="mouse_geterrormsg"><p> + +<quote> +<descrip> +<tag/Function/Return a readable error message for an error code. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/const char* __fastcall__ mouse_geterrormsg (unsigned char +code);/ +<tag/Description/The function returns an error message (in english) for the +error code passed parameter. +<tag/Limits/<itemize> +<item>The function will return "Unknown error" for invalid error codes. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_load_driver" name="mouse_load_driver">, +<ref id="mouse_uninstall" name="mouse_uninstall">, +<ref id="mouse_unload" name="mouse_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_hide<label id="mouse_hide"><p> + +<quote> +<descrip> +<tag/Function/Hide the mouse pointer. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void mouse_hide (void);/ +<tag/Description/The function hides the mouse pointer. It manages a counter +that is shared between <tt/<ref id="mouse_show" name="mouse_show">/ and +<tt/mouse_hide/ so that every call call to <tt/mouse_hide/ must be followed by +a call to <tt/<ref id="mouse_show" name="mouse_show">/ to make the mouse cursor +visible. +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_show" name="mouse_show"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_info<label id="mouse_info"><p> + +<quote> +<descrip> +<tag/Function/Return the state of the mouse buttons and the position of the +mouse. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_info (struct mouse_info* info);/ +<tag/Description/The function returns the state of the mouse buttons and the +position of the mouse in the <tt/mouse_info/ structure passed as parameter. +<tag/Limits/<itemize> +<item>The <tt/mouse_info/ struct is a superset of the <tt/mouse_pos/ struct, +so if you just need the mouse position, call <tt/<ref id="mouse_pos" +name="mouse_pos">/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_buttons" name="mouse_buttons">, +<ref id="mouse_pos" name="mouse_pos"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_install<label id="mouse_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded mouse driver. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ mouse_install (const struct +mouse_callbacks* c, void* driver);/ +<tag/Description/The function installs an already loaded mouse driver and +returns an error code. The <tt/mouse_callbacks/ structure passed as first +parameter contains pointers to routines needed to move or hide/show the mouse +pointer. Defaults for these routines are supplied by the library, so if you +can live with these defaults (which are platform specific), just pass a +pointer to <tt/mouse_def_callbacks/. The function may be used to install a +driver linked statically to the program. +<tag/Limits/<itemize> +<item>Not all drivers are able to detect if the supported hardware is really +present. +<item>After installing a driver, the mouse cursor is hidden. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_load_driver" name="mouse_load_driver">, +<ref id="mouse_uninstall" name="mouse_uninstall">, +<ref id="mouse_unload" name="mouse_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_ioctl<label id="mouse_ioctl"><p> + +<quote> +<descrip> +<tag/Function/Call the driver specific ioctl function. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ mouse_ioctl (unsigned char code, void* data);/ +<tag/Description/The function calls the IOCTL entry in the mouse driver, +which is driver specific. The <tt/code/ parameter will choose between +different IOCTL functions, and the <tt/data/ depends on code. The +function returns an error code. The purpose of this function is to allow +for driver specific extensions. See the documentation for a specific mouse +driver for supported ioctl calls. +<tag/Limits/<itemize> +<item>Calling this function is non portable, because each driver may +implement different ioctl calls (or none at all). +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_load_driver<label id="mouse_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load and initialize a mouse driver. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ mouse_load_driver (const struct +mouse_callbacks* c, const char* driver);/ +<tag/Description/Load a mouse driver into memory and initialize it. The +function returns an error code that tells if the call has been successful. The +<tt/mouse_callbacks/ structure passed as first parameter contains pointers to +routines needed to move or hide/show the mouse pointer. Defaults for these +routines are supplied by the library, so if you can live with these defaults +(which are platform specific), just pass a pointer to <tt/mouse_def_callbacks/. +<tag/Limits/<itemize> +<item>The driver is loaded by name, so currently you must know the type of +mouse that should be supported. There is no autodetect capability. +<item>Not all drivers are able to detect if the supported hardware is really +present. +<item>After installing a driver, the mouse cursor is hidden. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_install" name="mouse_install">, +<ref id="mouse_uninstall" name="mouse_uninstall">, +<ref id="mouse_unload" name="mouse_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_move<label id="mouse_move"><p> + +<quote> +<descrip> +<tag/Function/Move the mouse cursor to a specific position. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_move (int x, int y);/ +<tag/Description/The function updates the mouse position. If the mouse cursor +is visible, it is shown at the new position. +<tag/Limits/<itemize> +<item>The function does not check if the new position is within the bounding +box specified with <tt/<ref id="mouse_setbox" name="mouse_setbox">/. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_getbox" name="mouse_getbox">, +<ref id="mouse_setbox" name="mouse_setbox"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_pos<label id="mouse_pos"><p> + +<quote> +<descrip> +<tag/Function/Return the position of the mouse. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void __fastcall__ mouse_pos (struct mouse_pos* pos);/ +<tag/Description/The function returns the position of the mouse in the +<tt/mouse_pos/ structure passed as parameter. +<tag/Limits/<itemize> +<item>The <tt/mouse_pos/ struct is a subset of the <tt/mouse_info/ struct, +so if you do also need the mouse buttons, call <tt/<ref id="mouse_info" +name="mouse_info">/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_buttons" name="mouse_buttons">, +<ref id="mouse_info" name="mouse_info"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_show<label id="mouse_show"><p> + +<quote> +<descrip> +<tag/Function/Show the mouse pointer. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/void mouse_show (void);/ +<tag/Description/The function shows the mouse pointer. It manages a counter +that is shared between <tt/<ref id="mouse_hide" name="mouse_hide">/ and +<tt/mouse_show/. The mouse cursor is visible if there was one more call to +<tt/mouse_show/ than to <tt/<ref id="mouse_hide" name="mouse_hide">/. +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_hide" name="mouse_hide"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_uninstall<label id="mouse_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall an already loaded mouse driver. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char mouse_uninstall (void);/ +<tag/Description/The function uninstalls an already loaded mouse driver but +don't removes it from memory. +<tag/Limits/<itemize> +<item>If the driver has been loaded using <tt/<ref id="mouse_load_driver" +name="mouse_load_driver">/, <tt/<ref id="mouse_unload" name="mouse_unload">/ +should be used instead of <tt/mouse_uninstall/ so the driver is also removed +from memory. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_install" name="mouse_install">, +<ref id="mouse_load_driver" name="mouse_load_driver">, +<ref id="mouse_unload" name="mouse_unload"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>mouse_unload<label id="mouse_unload"><p> + +<quote> +<descrip> +<tag/Function/Unload a mouse driver. +<tag/Header/<tt/<ref id="mouse.h" name="mouse.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ mouse_unload (void);/ +<tag/Description/The function unloads a loaded mouse driver and frees all +memory allocated for the driver. +<tag/Limits/<itemize> +<item>The function does nothing if no driver is loaded. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="mouse_install" name="mouse_install">, +<ref id="mouse_load_driver" name="mouse_load_driver">, +<ref id="mouse_uninstall" name="mouse_uninstall"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>offsetof<label id="offsetof"><p> + +<quote> +<descrip> +<tag/Function/Calculate the offset of a struct or union member. +<tag/Header/<tt/<ref id="stddef.h" name="stddef.h">/ +<tag/Declaration/<tt/size_t offsetof (type, member);/ +<tag/Description/<tt/offsetof/ calculates the address offset of a <tt/struct/ +or <tt/union/ member. +<tag/Limits/<itemize> +<item>The function is actually a macro. +</itemize> +<tag/Availability/ISO 9899 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>open<label id="open"><p> + +<quote> +<descrip> +<tag/Function/Open and possibly create a file. +<tag/Header/<tt/<ref id="fcntl.h" name="fcntl.h">/ +<tag/Declaration/<tt/int open (const char* name, int flags, ...);/ +<tag/Description/<tt/open/ opens a file and returns the file descriptor +associated with it. On error, -1 is returned and an error code is stored in +<tt/errno/. Several flags may be passed to <tt/open/ that change the behaviour. +<tag/Limits/<itemize> +<item>POSIX specifies an additional <tt/mode/ argument that may be passed to +open, which is used as the permission mask when a new file is created. While +cc65 allows to pass this argument, it is ignored. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="close" name="close">, +<ref id="creat" name="creat"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>opendir<label id="opendir"><p> + +<quote> +<descrip> +<tag/Function/Open a directory. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/DIR* __fastcall__ opendir (const char* name);/ +<tag/Description/<tt/opendir/ opens a directory and returns the direcory +descriptor associated with it. On error, NULL is returned and an error code is +stored in <tt/errno/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="closedir" name="closedir">, +<ref id="readdir" name="readdir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>peekbsys<label id="peekbsys"><p> + +<quote> +<descrip> +<tag/Function/Read one byte from a location in the system bank. +<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, +<tt/<ref id="cbm510.h" name="cbm510.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ peekbsys (unsigned addr);/ +<tag/Description/<tt/peekbsys/ reads one byte from the given address in the +system bank (bank 15) of the CBM PET-II machines and returns it. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>This function may be a macro depending on the compiler options. The +actual function is accessible by #undef'ing the macro. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="PEEKW" name="PEEKW">, +<ref id="peekwsys" name="peekwsys">, +<ref id="pokebsys" name="pokebsys">, +<ref id="pokewsys" name="pokewsys"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>peekwsys<label id="peekwsys"><p> + +<quote> +<descrip> +<tag/Function/Read one word from a location in the system bank. +<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, +<tt/<ref id="cbm510.h" name="cbm510.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ peekwsys (unsigned addr);/ +<tag/Description/<tt/peekwsys/ reads one word from the given address in the +system bank (bank 15) of the CBM PET-II machines and returns it. Following +the usual 6502 conventions, the low byte is read from <tt/addr/, and the +high byte is read from <tt/addr+1/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The order in which the two bytes are read is undefined. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="PEEK" name="PEEK">, +<ref id="PEEKW" name="PEEKW">, +<ref id="peekbsys" name="peekbsys">, +<ref id="pokebsys" name="pokebsys">, +<ref id="pokewsys" name="pokewsys"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>perror<label id="perror"><p> + +<quote> +<descrip> +<tag/Function/Print an error message for the error in <tt/errno/. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/void __fastcall__ perror (const char* s);/ +<tag/Description/<tt/perror/ prints an error message to <tt/stderr/. If <tt/s/ +is not <tt/NULL/ and not an empty string, it is printed followed by a colon and +a blank. Then the error message for the current contents of <tt/errno/ is +printed followed by a newline. The message output is the same as returned by +<tt/<ref id="strerror" name="strerror">/ with an argument of <tt/errno/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_poserror" name="_poserror">, +<ref id="strerror" name="strerror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>pokebsys<label id="pokebsys"><p> + +<quote> +<descrip> +<tag/Function/Write one byte to a location in the system bank. +<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, +<tt/<ref id="cbm510.h" name="cbm510.h">/ +<tag/Declaration/<tt/void __fastcall__ pokebsys (unsigned addr, unsigned char val);/ +<tag/Description/<tt/pokebsys/ writes one byte to the given address in the +system bank (bank 15) of the CBM PET-II machines. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="POKE" name="POKE">, +<ref id="POKEW" name="POKEW">, +<ref id="peekbsys" name="peekbsys">, +<ref id="peekwsys" name="peekwsys">, +<ref id="pokewsys" name="pokewsys"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>pokewsys<label id="pokewsys"><p> + +<quote> +<descrip> +<tag/Function/Write one word to a location in the system bank. +<tag/Header/<tt/<ref id="cbm610.h" name="cbm610.h">/, +<tt/<ref id="cbm510.h" name="cbm510.h">/ +<tag/Declaration/<tt/void __fastcall__ pokewsys (unsigned addr, unsigned val);/ +<tag/Description/<tt/pokewsys/ writes one word to the given address in the +system bank (bank 15) of the CBM PET-II machines. Following the usual 6502 +conventions, the low byte of <tt/val/ is written to <tt/addr/, and the +high byte is written to <tt/addr+1/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The order in which the two bytes are written is undefined. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="POKE" name="POKE">, +<ref id="POKEW" name="POKEW">, +<ref id="peekbsys" name="peekbsys">, +<ref id="peekwsys" name="peekwsys">, +<ref id="pokebsys" name="pokebsys"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>qsort<label id="qsort"><p> + +<quote> +<descrip> +<tag/Function/Sort an array. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ qsort (void* base, size_t count, +size_t size, int (*compare) (const void*, const void*));/ +<tag/Description/<tt/qsort/ sorts an array according to a given compare +function <tt/compare/. <tt/base/ is the address of the array, <tt/count/ +is the number of elements, <tt/size/ the size of an element and <tt/compare/ +the function used to compare the members. +<tag/Limits/ +<itemize> +<item>If there are multiple members with the same key, the order after calling +the function is undefined. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="bsearch" name="bsearch"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>raise<label id="raise"><p> + +<quote> +<descrip> +<tag/Function/Send a signal to the executing program. +<tag/Header/<tt/<ref id="signal.h" name="signal.h">/ +<tag/Declaration/<tt/int __fastcall__ raise (int sig);/ +<tag/Description/<tt/raise/ sends the given signal to the program. If the +program has installed a signal handler for the signal, this signal handler +will be executed. If no handler has been installed, the default action for +the raised signal will be taken. The function returns zero on success, +nonzero otherwise. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="signal" name="signal"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>rand<label id="rand"><p> + +<quote> +<descrip> +<tag/Function/Return a pseudo random number. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/int rand (void);/ +<tag/Description/The function returns a pseudo random number +between 0 and <tt/RAND_MAX/ (exclusive). +<tag/Limits/<itemize> +<item>Without using <tt><ref id="srand" name="srand"></tt>, always the same +flow of numbers is generated. +<item>On startup, the function behaves as if <ref id="srand" name="srand"> +had been used with an argument of 1. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_randomize" name="_randomize">, +<ref id="srand" name="srand"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>readdir<label id="readdir"><p> + +<quote> +<descrip> +<tag/Function/Read a directory. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/struct dirent* __fastcall__ readdir (DIR* dir);/ +<tag/Description/<tt/readdir/ reads the next directory entry from the directory +stream pointed to by <tt/dir/. It stores the data in a <tt/dirent/ structure +and returns a pointer to it. If the end of directory is reached, or an error +occurs, NULL is returned. In case of errors, an error code is stored into +<tt/errno/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The returned pointer may point to a statically allocated instance of +<tt/struct dirent/, so it may get overwritten by subsequent calls to +<tt/readdir/. +<item>On several platforms, namely the CBMs and the Atari, the disk drives get +confused when opening/closing files between directory reads. So for example a +program that reads the list of files on a disk, and after each call to +<tt/readdir/, opens the file to process it, will fail.<newline> +Possible solutions are reading the directory into memory before processing the +file list, or to reset the directory by seeking to the correct position after +opening/closing a file: +<verb> + seekdir (DIR, telldir (DIR)); +</verb> +Platforms known to work without problems are: Apple. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="closedir" name="closedir">, +<ref id="opendir" name="opendir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>realloc<label id="realloc"><p> + +<quote> +<descrip> +<tag/Function/Change the size of an allocated memory block. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void* __fastcall__ realloc (void* block, size_t size);/ +<tag/Description/<tt/realloc/ changes the size of the memory block pointed to +by <tt/block/ to <tt/size/ bytes. If <tt/block/ is <tt/NULL/, <tt/realloc/ +behaves as if <tt/malloc/ had been called. If <tt/size/ is zero, <tt/realloc/ +behaves as if <tt/free/ had been called. On error (not enough memory +available), <tt/realloc/ returns <tt/NULL/. +<tag/Limits/ +<itemize> +<item>The part of the memory block that is returned will have its contents +unchanged. +<item>This function is somewhat dangerous to use. Be careful to save the +pointer you're passing somewhere else, otherwise +<tscreen><verb> + ptr = realloc (ptr, size); +</verb></tscreen> +will loose your only copy of <tt/ptr/ if <tt/realloc/ returns <tt/NULL/. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_heapadd" name="_heapadd">, +<ref id="_heapblocksize" name="_heapblocksize">, +<ref id="_heapmaxavail" name="_heapmaxavail">, +<ref id="_heapmemavail" name="_heapmemavail">, +<ref id="calloc" name="calloc">, +<ref id="free" name="free">, +<ref id="realloc" name="realloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>remove<label id="remove"><p> + +<quote> +<descrip> +<tag/Function/Delete a file. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ remove (const char* name);/ +<tag/Description/<tt/remove/ deletes the file with the given name. On success, +zero is returned. On error, -1 is returned and <tt/errno/ is set to an error +code describing the reason for the failure. +<tag/Limits/ +<itemize> +<item>This function is not available on all cc65 targets (depends on the +availability of file I/O). +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="rename" name="rename">, +<ref id="unlink" name="unlink"> +<tag/Example/ +<verb> +#include <stdio.h> + +#define FILENAME "helloworld" + +if (remove (FILENAME) == 0) { + printf ("We deleted %s successfully\n", FILENAME); +} else { + printf ("There was a problem deleting %s\n", FILENAME); +} +</verb> +</descrip> +</quote> + + +<sect1>rename<label id="rename"><p> + +<quote> +<descrip> +<tag/Function/Rename a file. +<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/ +<tag/Declaration/<tt/int __fastcall__ rename (const char* oldname, const char* newname);/ +<tag/Description/<tt/rename/ renames a file (gives it a new name). On success, +zero is returned. On error, -1 is returned and <tt/errno/ is set to an error +code describing the reason for the failure. +<tag/Limits/ +<itemize> +<item>This function is not available on all cc65 targets (depends on the +capabilities of the storage devices). +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="remove" name="remove"> +<tag/Example/ +<verb> +#include <stdio.h> + +#define OLDNAME "textfile.txt" +#define NEWNAME "textfile.bak" + +if (rename (OLDNAME, NEWNAME) == 0) { + printf ("Renamed %s to %s\n", OLDNAME, NEWNAME); +} else { + printf ("Error renaming %s to %s\n", OLDNAME, NEWNAME); +} +</verb> +</descrip> +</quote> + + +<sect1>reset_brk<label id="reset_brk"><p> + +<quote> +<descrip> +<tag/Function/Resets the break vector to its original value. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void reset_brk (void);/ +<tag/Description/<tt/reset_brk/ resets the break vector to the value it had +before a call to <tt/set_brk/. +<tag/Limits/ +<itemize> +<item>Since <tt/<ref id="set_brk" name="set_brk">/ installs an exit handler, +it is not strictly necessary to call this function as part of the cleanup when +the program ends. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="reset_irq" name="reset_irq">, +<ref id="set_brk" name="set_brk">, +<ref id="set_irq" name="set_irq"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>reset_irq<label id="reset_irq"><p> + +<quote> +<descrip> +<tag/Function/Resets the C level interrupt request vector. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void reset_irq (void);/ +<tag/Description/<tt/reset_irq/ resets the C level interrupt request vector. +<tag/Limits/ +<itemize> +<item>The original IRQ vector is restored on program termination even without +calling this function. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="reset_brk" name="reset_brk">, +<ref id="set_brk" name="set_brk">, +<ref id="set_irq" name="set_irq"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>revers<label id="revers"><p> + +<quote> +<descrip> +<tag/Function/Control revers character display. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ revers (unsigned char onoff);/ +<tag/Description/If the argument is non zero, the function enables reverse +character display. If the argument is zero, reverse character display is +switched off. The old value of the setting is returned. +<tag/Limits/<itemize> +<item>The function may not be supported by the hardware, in which case +the call is ignored. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="textcolor" name="textcolor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>rewinddir<label id="rewinddir"><p> + +<quote> +<descrip> +<tag/Function/Reset a directory stream. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/void __fastcall__ rewinddir (DIR* dir);/ +<tag/Description/<tt/rewinddir/ sets the position of the directory stream +pointed to by <tt/dir/ to the start of the directory. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="seekdir" name="seekdir">, +<ref id="telldir" name="telldir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>screensize<label id="screensize"><p> + +<quote> +<descrip> +<tag/Function/Return the dimensions of the text mode screen. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/void __fastcall__ screensize (unsigned char* x, unsigned char* y);/ +<tag/Description/The function returns the dimensions of the text mode screen. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoxy" name="gotoxy">, +<ref id="gotoy" name="gotoy">, +<ref id="wherex" name="wherex">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>seekdir<label id="seekdir"><p> + +<quote> +<descrip> +<tag/Function/Set the position of a directory stream. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/void __fastcall__ seekdir (DIR* dir, long offset);/ +<tag/Description/<tt/seekdir/ sets the position of the directory stream +pointed to by <tt/dir/ to the value given in <tt/offset/, which should be a +value returned by <tt/<ref id="telldir" name="telldir">/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="rewinddir" name="rewinddir">, +<ref id="telldir" name="telldir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ser_close<label id="ser_close"><p> + +<quote> +<descrip> +<tag/Function/Close the port and disable interrupts +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char ser_close (void);/ +<tag/Description/Close the port by clearing buffers and disable interrupts. +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/ +<verb> +#include <serial.h> + +static void initialize(){ + struct ser_params params = { + SER_BAUD_9600, + SER_BITS_8, + SER_STOP_1, + SER_PAR_MARK, + SER_HS_NONE + }; + ser_install(lynx_comlynx); // This will activate the ComLynx + CLI(); + ser_open(&params); +} +</verb> +</descrip> +</quote> + + +<sect1>ser_get<label id="ser_get"><p> + +<quote> +<descrip> +<tag/Function/Read a character from serial port. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_get (char* b);/ +<tag/Description/Get a character from the serial port. If no characters are +available, the function will return SER_ERR_NO_DATA, so this is not a fatal +error. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/ +Wait for a character to be available from a serial port. +<verb> +char ch; +while (ser_get(&ch) == SER_ERR_NO_DATA) + ; +</verb> +</descrip> +</quote> + + +<sect1>ser_install<label id="ser_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded driver and return an error code. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_install (void* driver);/ +<tag/Description/The function installs a driver that was already loaded into +memory (or linked statically to the program). It returns an error code +(<tt/SER_ERR_OK/ in case of success). +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="ser_load_driver" name="ser_load_driver">, +<ref id="ser_uninstall" name="ser_uninstall">, +<ref id="ser_unload" name="ser_unload"> +<tag/Example/<verb> +ser_install(lynx_comlynx); //Include the driver statically instead of loading it. +</verb> +</descrip> +</quote> + + +<sect1>ser_ioctl<label id="ser_ioctl"><p> + +<quote> +<descrip> +<tag/Function/Platform dependent code extensions. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ ser_ioctl (unsigned char code, void* data);/ +<tag/Description/Some platforms have extra serial functions that are not +supported by standard serial driver functions. You can extend the driver to support +this extra functionality bt using ser_ioctl functions. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>These functions are not easily portable to other cc65 platforms. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None +</descrip> +</quote> + +<sect1>ser_load_driver<label id="ser_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load and install a serial driver. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_load_driver (const char *name);/ +<tag/Description/Load and install the driver by name. +Will just load the driver and check if loading was successful. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ser_open<label id="ser_open"><p> + +<quote> +<descrip> +<tag/Function/Open the port by setting the port parameters and enable interrupts +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_open (const struct ser_params* params);/ +<tag/Description/Open the port by setting the port parameters and enable interrupts. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/ +<verb> +#include <serial.h> + +static void initialize(){ + struct ser_params params = { + SER_BAUD_9600, + SER_BITS_8, + SER_STOP_1, + SER_PAR_MARK, + SER_HS_NONE + }; + ser_install(lynx_comlynx); // This will activate the ComLynx + CLI(); + ser_open(&params); +} +</verb> +</descrip> +</quote> + + +<sect1>ser_put<label id="ser_put"><p> + +<quote> +<descrip> +<tag/Function/Write a character to a serial port. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_put (char b);/ +<tag/Description/Send a character via the serial port. There is a transmit +buffer, but transmitting is not done via interrupt. The function returns +SER_ERR_OVERFLOW if there is no space left in the transmit buffer. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/ +<verb> +ser_put('A'); +</verb> +</descrip> +</quote> + + +<sect1>ser_status<label id="ser_status"><p> + +<quote> +<descrip> +<tag/Function/Return the serial port status. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ ser_status (unsigned char* status);/ +<tag/Description/Return the serial port status. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None +</descrip> +</quote> + + +<sect1>ser_uninstall<label id="ser_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall the currently loaded driver but do not unload it. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char ser_uninstall (void);/ +<tag/Description/Uninstall the currently loaded driver but do not unload it. +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>ser_unload<label id="ser_unload"><p> + +<quote> +<descrip> +<tag/Function/Uninstall, then unload the currently loaded driver. +<tag/Header/<tt/<ref id="serial.h" name="serial.h">/ +<tag/Declaration/<tt/unsigned char ser_unload (void);/ +<tag/Description/Uninstall, then unload the currently loaded driver. +<tag/Availability/cc65 +<tag/See also/Other serial functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>set_brk<label id="set_brk"><p> + +<quote> +<descrip> +<tag/Function/Set the break vector to a user function. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void __fastcall__ set_brk (brk_handler func);/ +<tag/Description/<tt/set_brk/ allows a user program to handle breaks within the +program code by letting the vector point to a user written C function. The +runtime library installs a small stub that saves the registers into global +variables that may be accessed (and changed) by the break handler. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The stub saves the zero page registers used by the C runtime and switches +to a small break handler stack. This means that it is safe to execute C code, +even if C code was interrupted. Be careful however not to use too many local +variables, and do not enable stack checks for the handler function or any other +function called from it. +<item>The <tt/brk_pc/ variable points to the <tt/BRK/ instruction. If you want +the continue with the interrupted code, you have to adjust <tt/brk_pc/, +otherwise the <tt/BRK/ instruction will get executed over and over again. +<item>Since <tt/set_brk/ installs an exit handler, it is not strictly necessary +to call <tt/<ref id="reset_brk" name="reset_brk">/ as part of the cleanup when +the program terminates. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="reset_brk" name="reset_brk"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>set_irq<label id="set_irq"><p> + +<quote> +<descrip> +<tag/Function/Set the C level interrupt request vector to the given address. +<tag/Header/<tt/<ref id="6502.h" name="6502.h">/ +<tag/Declaration/<tt/void __fastcall__ set_irq (irq_handler f, void *stack_addr, size_t stack_size);/ +<tag/Description/<tt/set_irq/ allows a user program to handle interrupt requests +(IRQs) within the program code by letting the vector point to a user written C +function. The runtime library installs a small stub that saves the zero page +registers used by the C runtime before calling the handler function and restores +them after the handler function returns. Additionally the stub temporarily switches +the C runtime stack to the stack area provided as parameter. If the handler function +was set up to handle a "private", "exclusive" interrupt request source it must +return the value <tt/IRQ_HANDLED/ if and only if it has verified that the current +interrupt request actually stems from that source. In all other cases it must return +the value <tt/IRQ_NOT_HANDLED/. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The stub saves the registers and zero page locations used by the C runtime +and switches to the provided stack area. As a consequence, there is some +runtime overhead, but it it is safe to execute C code, even if other C code +was interrupted. Be careful however not to call C library functions, and do not +enable stack checks for the handler function or any other function called from +it. +<item>The interrupt vector is reset on function termination, so it's not +strictly necessary to call <tt/<ref id="reset_irq" name="reset_irq">/ as part +of the cleanup when the program terminates. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="reset_brk" name="reset_brk">, +<ref id="reset_irq" name="reset_irq">, +<ref id="set_brk" name="set_brk"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>setjmp<label id="setjmp"><p> + +<quote> +<descrip> +<tag/Function/Save the context for use with <tt/longjmp/. +<tag/Header/<tt/<ref id="setjmp.h" name="setjmp.h">/ +<tag/Declaration/<tt/int __fastcall__ setjmp (jmp_buf buf);/ +<tag/Description/The <tt/setjmp/ function saves the current context in <tt/buf/ +for subsequent use by the <tt/<ref id="longjmp" name="longjmp">/ function and +returns zero. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item><tt/setjmp/ is actually a macro as required by the ISO standard. +<item><tt/setjmp/ will not save the signal context. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="longjmp" name="longjmp"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>setlocale<label id="setlocale"><p> + +<quote> +<descrip> +<tag/Function/Selects a locale. +<tag/Header/<tt/<ref id="locale.h" name="locale.h">/ +<tag/Declaration/<tt/char* __fastcall__ setlocale (int category, const char* locale);/ +<tag/Description/<tt/setlocale/ sets or queries the program's locale. +<tag/Limits/ +<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>cc65 supports only the "C" locale, so calling this function to set a +different locale has no effect. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="localeconv" name="localeconv">, +<ref id="strcoll" name="strcoll"> +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>signal<label id="signal"><p> + +<quote> +<descrip> +<tag/Function/Install a signal handler. +<tag/Header/<tt/<ref id="signal.h" name="signal.h">/ +<tag/Declaration/<tt/__sigfunc __fastcall__ signal (int sig, __sigfunc func);/ +<tag/Description/<tt/signal/ installs a handler for the given signal. The +handler may either be a user supplied function, or one of the predefined +signal handlers <tt/SIG_IGN/ or <tt/SIG_DFL/. The function returns the +previous value if the signal , or the special function vector SIG_ERR in +case of an error. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="abort" name="abort">, +<ref id="raise" name="raise"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>sleep<label id="sleep"><p> + +<quote> +<descrip> +<tag/Function/Sleep for a specified amount of time. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/void __fastcall__ sleep (unsigned seconds);/ +<tag/Description/The function will return after the specified number of +seconds have elapsed. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/Example/None. +</descrip> +</quote> + + +<sect1>slow<label id="slow"><p> + +<quote> +<descrip> +<tag/Function/Switch the C128 into 1MHz mode. +<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/void slow (void);/ +<tag/Description/The function will switch the clock of the C128 to 1MHz. This +will halve the speed compared to fast mode. +<tag/Limits/<itemize> +<item>The function is specific to the C128. +</itemize> +<tag/Availability/C128 +<tag/See also/ +<ref id="fast" name="fast">, +<ref id="toggle_videomode" name="toggle_videomode">, +<ref id="videomode" name="videomode"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>srand<label id="srand"><p> + +<quote> +<descrip> +<tag/Function/Initialize the pseudo random number generator. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/void __fastcall__ srand (unsigned seed);/ +<tag/Description/The function initializes the random number generator using +the given seed. On program startup, the generator behaves as if <tt/srand/ has +been called with an argument of 1. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_randomize" name="_randomize">, +<ref id="rand" name="rand"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcasecmp<label id="strcasecmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings case insensitive. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strcasecmp (const char* s1, const char* s2);/ +<tag/Description/The <tt/strcasecmp/ function compares the two strings passed +as parameters without case sensitivity. It returns a value that is less than +zero if <tt/s1/ is less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, +and a value greater than zero if <tt/s1/ is greater than <tt/s2/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function is not available in strict ANSI mode. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strcmp" name="strcmp">, +<ref id="strcoll" name="strcoll">, +<ref id="stricmp" name="stricmp">, +<ref id="strncmp" name="strncmp">, +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcat<label id="strcat"><p> + +<quote> +<descrip> +<tag/Function/Concatentate two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strcat (char* s1, const char* s2);/ +<tag/Description/The <tt/strcat/ function appends a copy of the string +pointed to by s2 (including the terminating null byte) to the end of the +string pointed to by s1. The initial byte of s2 overwrites the null byte at +the end of s1. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>If copying takes place between objects that overlap, the behaviour +is undefined. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcpy" name="strcpy">, +<ref id="strncat" name="strncat">, +<ref id="strncpy" name="strncpy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strchr<label id="strchr"><p> + +<quote> +<descrip> +<tag/Function/Search for a character in a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strchr (const char* s, int c);/ +<tag/Description/The <tt/strchr/ function locates the first occurrence of <tt/c/ +(converted to a char) in the string pointed to by <tt/s/. The terminating null +byte is considered to be part of the string. Upon completion, the function +returns a pointer to the byte, or a null pointer if the byte was not found. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="memchr" name="memchr">, +<ref id="strrchr" name="strrchr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcmp<label id="strcmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strcmp (const char* s1, const char* s2);/ +<tag/Description/The <tt/strcmp/ function compares the two strings passed as +parameters. It returns a value that is less than zero if <tt/s1/ is less than +<tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a value greater than zero +if <tt/s1/ is greater than <tt/s2/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcasecmp" name="strcasecmp">, +<ref id="strcoll" name="strcoll">, +<ref id="stricmp" name="stricmp">, +<ref id="strncmp" name="strncmp"> +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcoll<label id="strcoll"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strcoll (const char* s1, const char* s2);/ +<tag/Description/The <tt/strcoll/ function compares the two strings passed as +parameters, according to the collating sequence set by <tt/<ref id="setlocale" +name="setlocale">/. It returns a value that is less than zero if <tt/s1/ is +less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a value greater +than zero if <tt/s1/ is greater than <tt/s2/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="setlocale" name="setlocale">, +<ref id="strcasecmp" name="strcasecmp">, +<ref id="strcmp" name="strcmp">, +<ref id="stricmp" name="stricmp">, +<ref id="strncmp" name="strncmp">, +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strcpy<label id="strcpy"><p> + +<quote> +<descrip> +<tag/Function/Copy a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strcpy (char* s1, const char* s2);/ +<tag/Description/The <tt/strcpy/ function copies the string pointed to by +<tt/s2/ (including the terminating null byte) into the array pointed to by +<tt/s1/. The function will always return <tt/s1/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>If copying takes place between objects that overlap, the behaviour +is undefined. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcat" name="strcat">, +<ref id="strncat" name="strncat">, +<ref id="strncpy" name="strncpy"> +<tag/Example/ +<verb> +#include <string.h> + +static char hello[14]; + +strcpy (hello, "Hello world!\n"); +</verb> +</descrip> +</quote> + + +<sect1>strcspn<label id="strcspn"><p> + +<quote> +<descrip> +<tag/Function/Compute the length of a substring. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/size_t __fastcall__ strcspn (const char* s, const char* set);/ +<tag/Description/The <tt/strcspn/ function computes and returns the length of +the substring pointed to by <tt/s/ which does <em>not</em> consist of +characters contained in the string <tt/set/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strspn" name="strspn">, +<ref id="strstr" name="strstr">, +<ref id="strtok" name="strtok"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strdup<label id="strdup"><p> + +<quote> +<descrip> +<tag/Function/Allocate a copy of a string on the heap. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strdup (const char* s);/ +<tag/Description/<tt/strdup/ allocates a memory block on the heap, big enough +to hold a copy of <tt/s/ including the terminating zero. If the allocation +fails, <tt/NULL/ is returned, otherwise <tt/s/ is copied into the allocated +memory block, and a pointer to the block is returned. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>It is up to the caller to free the allocated memory block. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="free" name="free">, +<ref id="malloc" name="malloc"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strerror<label id="strerror"><p> + +<quote> +<descrip> +<tag/Function/Return a string describing an error code. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strerror (int errcode);/ +<tag/Description/The <tt/strerror/ function returns a string describing the +given error code. If an invalid error code is passed, the string "Unknown +error" is returned, and <tt/errno/ is set to <tt/EINVAL/. In all other cases, +<tt/errno/ is left untouched. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>While the return type of the function is a <tt/char*/, the returned +string must not be modified by the caller! +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="_stroserror" name="_stroserror"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>stricmp<label id="stricmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings case insensitive. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ stricmp (const char* s1, const char* s2);/ +<tag/Description/The <tt/stricmp/ function compares the two strings passed as +parameters without case sensitivity. It returns a value that is less than zero +if <tt/s1/ is less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a +value greater than zero if <tt/s1/ is greater than <tt/s2/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function is not available in strict ANSI mode. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strcasecmp" name="strcasecmp">, +<ref id="strcmp" name="strcmp">, +<ref id="strcoll" name="strcoll">, +<ref id="strncmp" name="strncmp">, +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strlen<label id="strlen"><p> + +<quote> +<descrip> +<tag/Function/Return the length of a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/size_t __fastcall__ strlen (const char* s);/ +<tag/Description/The <tt/strlen/ function computes the number of bytes in the +string to which s points, not including the terminating null byte. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>When compiling with <tt/-Os/ (inline known standard functions), the +function does not work correctly for strings with more than 255 characters. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcpy" name="strcpy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strlower<label id="strlower"><p> + +<quote> +<descrip> +<tag/Function/Make a string lower case. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strlower (char* s);/ +<tag/Description/The <tt/strlower/ function will apply the <tt/tolower/ +function to each character of a string. The function will always return <tt/s/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function prototype is unavailable when compiling in strict ANSI mode. +<item>An alias name for this function is <tt/strlwr/. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strupper" name="strupper">, +<ref id="tolower" name="tolower"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strlwr<label id="strlwr"><p> + +<quote> +See <tt/strlower/. +</quote> + + +<sect1>strncat<label id="strncat"><p> + +<quote> +<descrip> +<tag/Function/Concatentate two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strncat (char* s1, const char* s2, size_t n);/ +<tag/Description/The <tt/strncat/ function appends not more than n characters +of the string pointed to by s2 to the end of the string pointed to by s1. The +terminating null character at the end of s1 is overwritten. A terminating null +character is appended to the result, even if not all of s2 is appended to s1. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>If copying takes place between objects that overlap, the behaviour +is undefined. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcpy" name="strcpy">, +<ref id="strncat" name="strncat">, +<ref id="strncpy" name="strncpy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strncmp<label id="strncmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strncmp (const char* s1, const char* s2, size_t count);/ +<tag/Description/The <tt/strncmp/ function compares not more than <tt/count/ +characters of the two strings passed as parameters. It returns a value that is +less than zero if the first <tt/count/ characters of <tt/s1/ are less than +<tt/s2/, zero if they are identical, and a value greater than zero they are +greater. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcasecmp" name="strcasecmp">, +<ref id="strcmp" name="strcmp">, +<ref id="strcoll" name="strcoll">, +<ref id="stricmp" name="stricmp">, +<ref id="strxfrm" name="strxfrm"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strncpy<label id="strncpy"><p> + +<quote> +<descrip> +<tag/Function/Copy part of a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strcpy (char* s1, const char* s2, size_t n);/ +<tag/Description/The <tt/strncpy/ function copies not more than n bytes from +the array pointed to by <tt/s2/ to the array pointed to by <tt/s1/. If the array +pointed to by <tt/s2/ is a string that is shorter than n bytes, null bytes are +appended to the copy in the array pointed to by <tt/s1/, until <tt/n/ bytes are +written. The function will always return <tt/s1/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. If there is no null byte in the first <tt/n/ +bytes of the array pointed to by <tt/s2/, the result is not null-terminated. +<item>If copying takes place between objects that overlap, the behaviour is +undefined. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcat" name="strcat">, +<ref id="strcpy" name="strcpy">, +<ref id="strncat" name="strncat"> +<tag/Example/ +<verb> +#include <string.h> + +static char hello[6]; + +strcpy (hello, "Hello world!\n", sizeof (hello) - 1); +hello[5] = '\0'; +</verb> +</descrip> +</quote> + + +<sect1>strrchr<label id="strrchr"><p> + +<quote> +<descrip> +<tag/Function/Search for a character in a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strrchr (const char* s, int c);/ +<tag/Description/The <tt/strrchr/ function locates the last occurrence of <tt/c/ +(converted to a char) in the string pointed to by <tt/s/. The terminating null +byte is considered to be part of the string. Upon completion, the function +returns a pointer to the byte, or a null pointer if the byte was not found. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strchr" name="strchr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strspn<label id="strspn"><p> + +<quote> +<descrip> +<tag/Function/Compute the length of a substring. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/size_t __fastcall__ strspn (const char* s, const char* set);/ +<tag/Description/The <tt/strspn/ function computes and returns the length of +the substring pointed to by <tt/s/ which does consist only of characters +contained in the string <tt/set/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcspn" name="strcspn">, +<ref id="strstr" name="strstr"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strstr<label id="strstr"><p> + +<quote> +<descrip> +<tag/Function/Find a substring. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strstr (const char* str, const char* substr);/ +<tag/Description/<tt/strstr/ searches for the first occurance of the string +<tt/substr/ within <tt/str/. If found, it returns a pointer to the copy, +otherwise it returns <tt/NULL/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcspn" name="strcspn">, +<ref id="strspn" name="strspn"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strtok<label id="strtok"><p> + +<quote> +<descrip> +<tag/Function/Break a string into tokens. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strtok (char* s1, const char* s2);/ +<tag/Description/<tt/strtok/ will break the string s1 into a sequence of +tokens, which are delimited by characters from the string s2. The first call +to <tt/strtok/ will return a pointer to the first token in the string s1. +Following calls must pass a <tt/NULL/ pointer as s1 in order to get the next +token in the string. Different sets of delimiters may be used for the +subsequent calls to <tt/strtok/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item><tt/strtok/ will modify the string s1. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcspn" name="strcspn">, +<!-- <ref id="strpbrk" name="strpbrk"> --> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strxfrm<label id="strxfrm"><p> + +<quote> +<descrip> +<tag/Function/Transform a string. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/size_t __fastcall__ strxfrm (char* s1, const char* s2, size_t n);/ +<tag/Description/The <tt/strxfrm/ function transforms the string pointed to by +s2 and places the resulting string into the string pointed to by s1. The +transformation is such that if the <tt/strcmp/ function is applied to two +transformed strings, it returns a value greater than, equal to, or less than +zero, corresponding to the result of the <tt/strcoll/ function applied to the +same two original strings. No more than n characters are placed into the +resulting array pointed to by s1, including the terminating null character. +<tag/Limits/<itemize> +<item><tt/s1/ and <tt/s2/ must not point to the same memory area, otherwise +the behaviour is undefined. +<item>If <tt/n/ is zero, <tt/s1/ may be a NULL pointer. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>Since cc65 doesn't support different charcter sets, <tt/strxfrm/ will +just copy s2 to s1 using <tt><ref id="strncpy" name="strncpy"></tt>. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="strcmp" name="strcmp">, +<ref id="strcoll" name="strcoll">, +<ref id="strncpy" name="strncpy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strupper<label id="strupper"><p> + +<quote> +<descrip> +<tag/Function/Make a string upper case. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/char* __fastcall__ strupper (char* s);/ +<tag/Description/The <tt/strupper/ function will apply the <tt/toupper/ +function to each character of a string. The function will always return <tt/s/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function prototype is unavailable when compiling in strict ANSI mode. +<item>An alias name for this function is <tt/strupr/. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strlower" name="strlower"> +<ref id="toupper" name="toupper"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>strupr<label id="strupr"><p> + +<quote> +See <tt/strupper/. +</quote> + + +<sect1>telldir<label id="telldir"><p> + +<quote> +<descrip> +<tag/Function/Return the current position of a directory stream. +<tag/Header/<tt/<ref id="dirent.h" name="dirent.h">/ +<tag/Declaration/<tt/long __fastcall__ telldir (DIR* dir);/ +<tag/Description/<tt/telldir/ returns the current position of a directory +stream. The return value may be used in subsequent calls to +<tt/<ref id="seekdir" name="seekdir">/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="seekdir" name="seekdir">, +<ref id="telldir" name="telldir"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>textcolor<label id="textcolor"><p> + +<quote> +<descrip> +<tag/Function/Set the text color. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ textcolor (unsigned char color);/ +<tag/Description/The function will set a new text color. It returns the old +(current) text color. Text output using any <tt/conio.h/ function will use +the color set by this function. +<tag/Limits/<itemize> +<item>Text colors are system dependent. The function may have no effect +on systems where the text color cannot be changed. +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="bgcolor" name="bgcolor">, +<ref id="bordercolor" name="bordercolor"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_arc<label id="tgi_arc"><p> + +<quote> +<descrip> +<tag/Function/Draw an elliptic arc in the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_arc (int x, int y, +unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);/ +<tag/Description/The function draws an elliptic arc with center at x/y and +radii rx/ry using the current drawing color. The arc covers the angle +between sa and ea (startangle and endangle), which must be in the range +0..360. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function behaves unexpectedly or may crash if the angles are out +of range. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_bar" name="tgi_bar">, +<ref id="tgi_circle" name="tgi_circle">, +<ref id="tgi_ellipse" name="tgi_ellipse">, +<ref id="tgi_pieslice" name="tgi_pieslice">, +<ref id="tgi_setcolor" name="tgi_setcolor"> +<tag/Example/<verb> +/* Draw the upper half of an ellipse */ +tgi_setcolor(TGI_COLOR_BLUE); +tgi_arc (50, 50, 40, 20, 0, 180); +</verb> +</descrip> +</quote> + + +<sect1>tgi_bar<label id="tgi_bar"><p> + +<quote> +<descrip> +<tag/Function/The function fills a rectangle on the drawpage with the current +color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_bar (int x1, int y1, int x2, int y2);/ +<tag/Description/The function fills a rectangle on the drawpage with the current +color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi function +<tag/Example/<verb> +tgi_setcolor(TGI_COLOR_GREEN); +tgi_bar(10, 10, 100, 60); +</verb> +</descrip> +</quote> + + +<sect1>tgi_circle<label id="tgi_circle"><p> + +<quote> +<descrip> +<tag/Function/The function draws a circle in the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_circle (int x, int y, unsigned char radius);/ +<tag/Description/The function draws a circle in the current color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_arc" name="tgi_arc">, +<ref id="tgi_bar" name="tgi_bar">, +<ref id="tgi_ellipse" name="tgi_ellipse">, +<ref id="tgi_pieslice" name="tgi_pieslice">, +<ref id="tgi_setcolor" name="tgi_setcolor"> +<tag/Example/<verb> +tgi_setcolor(TGI_COLOR_BLACK); +tgi_circle(50, 40, 40); +</verb> +</descrip> +</quote> + + +<sect1>tgi_clear<label id="tgi_clear"><p> + +<quote> +<descrip> +<tag/Function/Clear the drawpage +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_clear (void);/ +<tag/Description/Clear the drawpage +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_done<label id="tgi_done"><p> + +<quote> +<descrip> +<tag/Function/End graphics mode, switch back to text mode. +Will NOT uninstall or unload the driver! +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_done (void);/ +<tag/Description/End graphics mode, switch back to text mode. +Will NOT uninstall or unload the driver! +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_ellipse<label id="tgi_ellipse"><p> + +<quote> +<descrip> +<tag/Function/The function draws an ellipse in the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_ellipse (int x, int y, unsigned char rx, unsigned char ry);/ +<tag/Description/The function draws an ellipse at position x/y with radii +rx and ry, using the current drawing color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_arc" name="tgi_arc">, +<ref id="tgi_bar" name="tgi_bar">, +<ref id="tgi_circle" name="tgi_circle">, +<ref id="tgi_pieslice" name="tgi_pieslice">, +<ref id="tgi_setcolor" name="tgi_setcolor"> +<tag/Example/<verb> +tgi_setcolor(TGI_COLOR_RED); +tgi_ellipse (50, 40, 40, 20); +</verb> +</descrip> +</quote> + + +<sect1>tgi_free_vectorfont<label id="tgi_free_vectorfont"><p> + +<quote> +<descrip> +<tag/Function/Free a vector font that was previously loaded into memory. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_free_vectorfont (const tgi_vectorfont* font);/ +<tag/Description/Free a vector font that was previously loaded into memory. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_load_vectorfont" name="tgi_load_vectorfont">, +<ref id="tgi_install_vectorfont" name="tgi_install_vectorfont"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getaspectratio<label id="tgi_getaspectratio"><p> + +<quote> <descrip> <tag/Function/Return the pixel aspect ratio. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getaspectratio (void);/ +<tag/Description/The function returns the pixel aspect ratio for the current +driver and display as an 8.8 fixed point value. It may be used to correct +geometric shapes so they look correct on the display. As an example, a circle +with a radius of 100 pixels may look elliptic on some driver/display +combinations if the aspect ratio is not 1.00. +<tag/Limits/<itemize> +<item>The aspect ratio is encoded in the TGI driver which assumes a "standard" +monitor for the given platform. The aspect ratio may be wrong if another +monitor is used. +<item>No TGI function will use the aspect ratio. It is up to the programmer to +make use of it. +<item>The <ref id="tgi_setaspectratio" name="tgi_setaspectratio"> function can +be used to change the aspect ratio for a loaded driver. The value is not reset +by <ref id="tgi_init" name="tgi_init">, so if a driver is linked statically to +an application, switching into and out of graphics mode will not restore the +original aspect ratio. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_setaspectratio" name="tgi_setaspectratio"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getcolor<label id="tgi_getcolor"><p> + +<quote> +<descrip> +<tag/Function/Return the current drawing color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char tgi_getcolor (void);/ +<tag/Description/The actual color is an index to a palette. During tgi_init +you will get a default palette. The number of colors depend on the platform. +All platforms recognize at least TGI_COLOR_BLACK and TGI_COLOR_WHITE. But some +platforms have many more predefined colors. If you paint using TGI_COLOR_GREEN +and then you change the green of the palette to blue using tgi_setpalette then +after this painting in TGI_COLOR_GREEN will actually be blue. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/<verb> +color = tgi_getcolor(); +</verb> +</descrip> +</quote> + + +<sect1>tgi_getcolorcount<label id="tgi_getcolorcount"><p> + +<quote> +<descrip> +<tag/Function/Get the number of available colors. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char tgi_getcolorcount (void);/ +<tag/Description/Tgi platforms use indexed color palettes. This function +returns the number of entries we can use in the palette. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/<verb> +if (tgi_getcolorcount() == 2) { + printf("Only monochrome graphics is supported\n"); +} +</verb> +</descrip> +</quote> + + +<sect1>tgi_getdefpalette<label id="tgi_getdefpalette"><p> + +<quote> +<descrip> +<tag/Function/Get the palette installed by default. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/const unsigned char* tgi_getdefpalette (void);/ +<tag/Description/The tgi driver has a default palette that is active at startup. +The named colors TGI_COLOR_BLACK, TGI_COLOR_WHITE, TGI_COLOR_RED... need this +palette to work correctly. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_geterror<label id="tgi_geterror"><p> + +<quote> +<descrip> +<tag/Function/Return the error code for the last operation. +This will also clear the error. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char tgi_geterror (void);/ +<tag/Description/Return the error code for the last operation. +This will also clear the error. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_geterrormsg<label id="tgi_geterrormsg"><p> + +<quote> +<descrip> +<tag/Function/Get an error message describing the error. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/const char* __fastcall__ tgi_geterrormsg (unsigned char code);/ +<tag/Description/Get an error message describing the error. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getmaxcolor<label id="tgi_getmaxcolor"><p> + +<quote> +<descrip> +<tag/Function/Get the highest index of the palette. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char tgi_getmaxcolor (void);/ +<tag/Description/Get the highest index of the palette. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getmaxx<label id="tgi_getmaxx"><p> + +<quote> +<descrip> +<tag/Function/Get the maximum x coordinate that can be used on this screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getmaxx (void);/ +<tag/Description/Get the maximum x coordinate that can be used on this screen. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getmaxy<label id="tgi_getmaxy"><p> + +<quote> +<descrip> +<tag/Function/Get the maximum y coordinate that can be used on this screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getmaxy (void);/ +<tag/Description/Get the maximum y coordinate that can be used on this screen. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getpagecount<label id="tgi_getpagecount"><p> + +<quote> +<descrip> +<tag/Function/Return the number of screen pages available. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getpagecount (void);/ +<tag/Description/Return the number of screen pages available. +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_setdrawpage" name="tgi_setdrawpage">, +<ref id="tgi_setviewpage" name="tgi_setviewpage"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getpalette<label id="tgi_getpalette"><p> + +<quote> +<descrip> +<tag/Function/Get the palette installed. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/const unsigned char* tgi_getpalette (void);/ +<tag/Description/Get the palette installed. +<tag/Availability/cc65 +<tag/See also/Other tgi functions +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getpixel<label id="tgi_getpixel"><p> + +<quote> +<descrip> +<tag/Function/Get the color of a pixel from the viewpage. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ tgi_getpixel (int x, int y);/ +<tag/Description/Get the color of a pixel from the viewpage. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getxres<label id="tgi_getxres"><p> + +<quote> +<descrip> +<tag/Function/Get number of horisontal pixels on the screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getxres (void);/ +<tag/Description/Get number of horisontal pixels on the screen. +This is same as tgi_maxx()+1. +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_getyres<label id="tgi_getyres"><p> + +<quote> +<descrip> +<tag/Function/Get number of vertical pixels on the screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned tgi_getyres (void);/ +<tag/Description/Get number of vertical pixels on the screen. +This is same as tgi_maxy()+1. +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_gotoxy<label id="tgi_gotoxy"><p> + +<quote> +<descrip> +<tag/Function/Set graphics cursor at x, y. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_gotoxy (int x, int y);/ +<tag/Description/Set graphics cursor at x, y. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_init<label id="tgi_init"><p> + +<quote> +<descrip> +<tag/Function/Initialize the already loaded graphics driver. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_init (void);/ +<tag/Description/The tgi_init function will set the default palette to the +hardware. +<tag/Limits/<itemize> +<item><tt/tgi_init/ will not clear the screen. This allows switching between +text and graphics mode on platforms that have separate memory areas for the +screens. If you want the screen cleared, call <tt/<ref id="tgi_clear" +name="tgi_clear">/ after <tt/tgi_init/. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it. +tgi_init(); //Set up the default palette and clear the screen. +</verb> +</descrip> +</quote> + + +<sect1>tgi_install<label id="tgi_install"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded driver and return an error code. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ tgi_install (void* driver);/ +<tag/Description/The function installs a driver that was already loaded into +memory (or linked statically to the program). It returns an error code +(<tt/TGI_ERR_OK/ in case of success). +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_load_driver" name="tgi_load_driver">, +<ref id="tgi_uninstall" name="tgi_uninstall">, +<ref id="tgi_unload" name="tgi_unload"> +<tag/Example/<verb> +tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it. +tgi_init(); //Set up the default palette and clear the screen. +</verb> +</descrip> +</quote> + + +<sect1>tgi_install_vectorfont<label id="tgi_install_vectorfont"><p> + +<quote> +<descrip> +<tag/Function/Install an already loaded driver and return an error code. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_install_vectorfont (const tgi_vectorfont* font);/ +<tag/Description/ +Install a vector font for use. More than one vector font can be loaded, +but only one can be active. This function is used to tell which one. Call +with a NULL pointer to uninstall the currently installed font. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_load_vectorfont" name="tgi_load_vectorfont">, +<ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_ioctl<label id="tgi_ioctl"><p> + +<quote> +<descrip> +<tag/Function/Platform dependent code extensions. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ tgi_ioctl (unsigned char code, void* data);/ +<tag/Description/Some platforms have extra display hardware that is not +supported by standard tgi functions. You can extend the driver to support +this extra hardware using tgi_ioctl functions. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>These functions are not easily portable to other cc65 platforms. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +#define tgi_sprite(spr) tgi_ioctl(0, (void*)(spr)) +#define tgi_flip() tgi_ioctl(1, (void*)0) +#define tgi_setbgcolor(bgcol) tgi_ioctl(2, (void*)(bgcol)) +#define tgi_setframerate(rate) tgi_ioctl(3, (void*)(rate)) +#define tgi_busy() tgi_ioctl(4, (void*)0) +#define tgi_updatedisplay() tgi_ioctl(4, (void*)1) +if (!tgi_busy()) { + tgi_sprite(&background); + tgi_setcolor(TGI_COLOR_BLUE); + tgi_outttextxy(20,40,"Hello World"); + tgi_updatedisplay(); +} +</verb> +</descrip> +</quote> + + +<sect1>tgi_line<label id="tgi_line"><p> + +<quote> +<descrip> +<tag/Function/Draw a line in the current drawing color. +The graphics cursor will be set to x2/y2 by this call. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_line (int x1, int y1, int x2, int y2);/ +<tag/Description/Draw a line in the current drawing color. +The graphics cursor will be set to x2/y2 by this call. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_lineto<label id="tgi_lineto"><p> + +<quote> +<descrip> +<tag/Function/Draw a line in the current drawing color from the graphics +cursor to the new end point. The graphics cursor will be updated to x2/y2. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_lineto (int x2, int y2);/ +<tag/Description/Draw a line in the current drawing color from the graphics +cursor to the new end point. The graphics cursor will be updated to x2/y2. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_load_driver<label id="tgi_load_driver"><p> + +<quote> +<descrip> +<tag/Function/Load and install the given driver. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_load_driver (const char *name);/ +<tag/Description/Load and install the driver by name. +Will just load the driver and check if loading was successful. +Will not switch to graphics mode. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_load_vectorfont<label id="tgi_load_vectorfont"><p> + +<quote> +<descrip> +<tag/Function/Load the given vector font. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/const tgi_vectorfont* __fastcall__ tgi_load_vectorfont (const char* name);/ +<tag/Description/ +Load a vector font into memory and return it. In case of errors, NULL is +returned and an error is set, which can be retrieved using tgi_geterror. +To use the font, it has to be installed using tgi_install_vectorfont. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_install_vectorfont" name="tgi_install_vectorfont">, +<ref id="tgi_free_vectorfont" name="tgi_free_vectorfont"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_outtext<label id="tgi_outtext"><p> + +<quote> +<descrip> +<tag/Function/Output text at the current graphics cursor position. +The graphics cursor is moved to the end of the text. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_outtext (const char* s);/ +<tag/Description/Output text at the current graphics cursor position. +The graphics cursor is moved to the end of the text. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_outtextxy<label id="tgi_outtextxy"><p> + +<quote> +<descrip> +<tag/Function/Output text at the given cursor position. +The graphics cursor is moved to the end of the text. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_outtextxy (int x, int y, const char* s);/ +<tag/Description/Output text at the given cursor position. +The graphics cursor is moved to the end of the text. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_pieslice<label id="tgi_pieslice"><p> + +<quote> +<descrip> +<tag/Function/Draw an elliptic pie slice in the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_pie slice (int x, int y, +unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);/ +<tag/Description/The function draws an elliptic pie slice with center at x/y +and radii rx/ry using the current drawing color. The pie slice covers the angle +between sa and ea (startangle and endangle), which must be in the range +0..360. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function behaves unexpectedly or may crash if the angles are out +of range. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_bar" name="tgi_arc">, +<ref id="tgi_bar" name="tgi_bar">, +<ref id="tgi_circle" name="tgi_circle">, +<ref id="tgi_ellipse" name="tgi_ellipse">, +<ref id="tgi_setcolor" name="tgi_setcolor"> +<tag/Example/<verb> +/* Draw the closed upper half of an ellipse */ +tgi_setcolor(TGI_COLOR_BLUE); +tgi_pieslice (50, 50, 40, 20, 0, 180); +</verb> +</descrip> +</quote> + + +<sect1>tgi_setaspectratio<label id="tgi_setaspectratio"><p> + +<quote> <descrip> <tag/Function/Set the pixel aspect ratio. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setaspectratio (unsigned ratio);/ +<tag/Description/The function sets the pixel aspect ratio for the current +driver and display. The argument is an 8.8 fixed point value. The aspect ratio +may be used to correct geometric shapes so they look correct on a given +display. As an example, a circle with a radius of 100 pixels may look elliptic +on some driver/display combinations if the aspect ratio is not 1.00. +<tag/Limits/<itemize> +<item>The aspect ratio is encoded in the TGI driver which assumes a "standard" +monitor for the given platform. The aspect ratio may be wrong if another +monitor is used. +<item>No TGI function will use the aspect ratio. It is up to the programmer to +make use of it. +<item>The <tt/tgi_setaspectratio/ function can be used to change the aspect +ratio for a loaded driver. The value is not reset by <ref id="tgi_init" +name="tgi_init">, so if a driver is linked statically to an application, +switching into and out of graphics mode will not restore the original aspect +ratio. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_getaspectratio" name="tgi_getaspectratio"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tgi_setcolor<label id="tgi_setcolor"><p> + +<quote> +<descrip> +<tag/Function/Set color to be used in future draw operations. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setcolor (unsigned char color);/ +<tag/Description/Set color to be used in future draw operations. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +tgi_setcolor(TGI_COLOR_BLACK); +tgi_bar(0,0,30,30); +tgi_setcolor(TGI_COLOR_WHITE); +tgi_bar(10,10,20,20); +</verb> +</descrip> +</quote> + +<sect1>tgi_setdrawpage<label id="tgi_setdrawpage"><p> + +<quote> +<descrip> +<tag/Function/Set the page for drawing. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setdrawpage (unsigned char page);/ +<tag/Description/If the drawpage and the viewpage are the same then all drawing +is seen immediately as it is drawn. For double buffered games you can set the +drawpage to a different page than the viewpage. This lets you draw the next +screen in the background and when the screen is ready you display it. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +tgi_setdrawpage(1); +tgi_outtextxy(10, 10, "Hello World"); +tgi_setviewpage(1); // Show page 1 +tgi_setdrawpage(0); +tgi_outtextxy(10, 10, "Creating next frame"); +... +tgi_setviewpage(0); // Show page 0 +</verb> +</descrip> +</quote> + +<sect1>tgi_setpalette<label id="tgi_setpalette"><p> + +<quote> +<descrip> +<tag/Function/Set the palette (not available with all drivers/hardware). +Palette is a pointer to as many entries as there are colors. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setpalette (const unsigned char* palette);/ +<tag/Description/Set the palette (not available with all drivers/hardware). +Palette is a pointer to as many entries as there are colors. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_setpixel<label id="tgi_setpixel"><p> + +<quote> +<descrip> +<tag/Function/Plot a pixel on the drawpage with the current color. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setpixel (int x, int y);/ +<tag/Description/Plot a pixel on the drawpage with the current color. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_setviewpage<label id="tgi_setviewpage"><p> + +<quote> +<descrip> +<tag/Function/Set page to be visible on screen. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_setviewpage (unsigned char page);/ +<tag/Description/If the drawpage and the viewpage are the same then all drawing +is seen immediately as it is drawn. For double buffered games you can set the +drawpage to a different page than the viewpage. This lets you draw the next +screen in the background and when the screen is ready you display it. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/<verb> +tgi_setdrawpage(1); +tgi_outtextxy(10, 10, "Hello World"); +tgi_setviewpage(1); // Show page 1 +tgi_setdrawpage(0); +tgi_outtextxy(10, 10, "Creating next frame"); +... +tgi_setviewpage(0); // Show page 0 +</verb> +</descrip> +</quote> + +<sect1>tgi_gettextheight<label id="tgi_gettextheight"><p> + +<quote> +<descrip> +<tag/Function/Calculate the height of the text in pixels according to +the current text style. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ tgi_gettextheight (const char* s);/ +<tag/Description/Calculate the height of the text in pixels according to +the current text style. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_settextscale<label id="tgi_settextscale"><p> + +<quote> +<descrip> +<tag/Function/Set the scaling for text output. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_settextscale (unsigned width, unsigned height);/ +<tag/Description/ +Set the scaling for text output. The scaling factors for width and height +are 8.8 fixed point values. This means that $100 = 1 $200 = 2 etc. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_settextstyle" name="tgi_settextstyle"> +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_settextstyle<label id="tgi_settextstyle"><p> + +<quote> +<descrip> +<tag/Function/Set the style for text output. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void __fastcall__ tgi_settextstyle (unsigned char magx, unsigned char magy, unsigned char dir, unsigned char font);/ +<tag/Description/Set the style for text output. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="tgi_settextscale" name="tgi_settextscale"> +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_gettextwidth<label id="tgi_gettextwidth"><p> + +<quote> +<descrip> +<tag/Function/Calculate the width of the text in pixels according to the current text style. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ tgi_gettextwidth (const char* s);/ +<tag/Description/Calculate the width of the text in pixels according to the current text style. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_uninstall<label id="tgi_uninstall"><p> + +<quote> +<descrip> +<tag/Function/Uninstall the currently loaded driver but do not unload it. +Will call tgi_done if necessary. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_uninstall (void);/ +<tag/Description/Uninstall the currently loaded driver but do not unload it. +Will call tgi_done if necessary. +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>tgi_unload<label id="tgi_unload"><p> + +<quote> +<descrip> +<tag/Function/Uninstall, then unload the currently loaded driver. +Will call tgi_done if necessary. +<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/ +<tag/Declaration/<tt/void tgi_unload (void);/ +<tag/Description/Uninstall, then unload the currently loaded driver. +Will call tgi_done if necessary. +<tag/Availability/cc65 +<tag/See also/Other tgi functions. +<tag/Example/None. +</descrip> +</quote> + +<sect1>time<label id="time"><p> + +<quote> +<descrip> +<tag/Function/Get the time. +<tag/Header/<tt/<ref id="time.h" name="time.h">/ +<tag/Declaration/<tt/time_t __fastcall__ time (time_t* t);/ +<tag/Description/The function returns the time since the 1970-01-01 00:00:00 +measured in seconds. If the pointer <tt/t/ is not <tt/NULL/, the function +result will also be stored there. If no time is available, <tt/(time_t)-1/ is +returned and <tt/errno/ is set to <tt/ENOSYS/. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +<item>Many platforms supported by cc65 do not have a realtime clock, so the +returned value may not be valid. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="clock" name="clock"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>toggle_videomode<label id="toggle_videomode"><p> + +<quote> +<descrip> +<tag/Function/Toggle between 40 and 80 column mode. +<tag/Header/<tt/<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/void toggle_videomode (void);/ +<tag/Description/Toggle between 40 and 80 column mode. The settings for the +old mode (cursor position, color and so on) are saved and restored together +with the mode. +<tag/Limits/<itemize> +<item>The function is specific to the C128. +<item>This function is deprecated. Please use <ref id="videomode" +name="videomode"> instead! +</itemize> +<tag/Availability/C128 +<tag/See also/ +<ref id="fast" name="fast">, +<ref id="slow" name="slow">, +<ref id="videomode" name="videomode"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>tolower<label id="tolower"><p> + +<quote> +<descrip> +<tag/Function/Convert a character into its lower case representation. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ tolower (int c);/ +<tag/Description/The function returns the given character converted to lower +case. If the given character is not a letter, it is returned unchanged. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="islower" name="islower">, +<ref id="isupper" name="isupper">, +<ref id="toupper" name="toupper"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>toupper<label id="toupper"><p> + +<quote> +<descrip> +<tag/Function/Convert a character into its upper case representation. +<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/ +<tag/Declaration/<tt/int __fastcall__ toupper (int c);/ +<tag/Description/The function returns the given character converted to upper +case. If the given character is not a letter, it is returned unchanged. +<tag/Limits/<itemize> +<item>The function is only available as fastcall function, so it may +only be used in presence of a prototype. +</itemize> +<tag/Availability/ISO 9899 +<tag/See also/ +<ref id="islower" name="islower">, +<ref id="isupper" name="isupper">, +<ref id="tolower" name="tolower"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>ultoa<label id="ultoa"><p> + +<quote> +<descrip> +<tag/Function/Convert an unsigned long integer into a string. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ ultoa (unsigned long val, char* buf, int radix);/ +<tag/Description/<tt/itoa/ converts the unsigned long integer <tt/val/ into a +string using <tt/radix/ as the base. +<tag/Limits/<itemize> +<item>There are no provisions to prevent a buffer overflow. +<item>The function is non standard, so it is not available in strict ANSI mode. +You should probably use <tt/sprintf/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="atol" name="atol">, +<ref id="itoa" name="itoa">, +<ref id="ltoa" name="ltoa">, +<ref id="utoa" name="utoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>unlink<label id="unlink"><p> + +<quote> +<descrip> +<tag/Function/Delete a file. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/int __fastcall__ unlink (const char* name);/ +<tag/Description/<tt/unlink/ deletes the file with the given name. On success, +zero is returned. On error, -1 is returned and <tt/errno/ is set to an error +code describing the reason for the failure. +<tag/Limits/ +<itemize> +<item>The use of this function is discouraged. Please use <tt/<ref id="remove" +name="remove">/ instead, which is a native ANSI C function and does the same. +<item>This function is not available on all cc65 targets (depends on the +availability of file I/O). +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>Instead of <tt/unlink/, <tt/<ref id="remove" name="remove">/ should be +used, which has the same semantics, but is more portable, because it conforms +to the ISO C standard. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/See also/ +<ref id="remove" name="remove"> +<tag/Example/ +<verb> +#include <stdio.h> +#include <unistd.h> + +#define FILENAME "helloworld" + +if (unlink (FILENAME) == 0) { + printf ("We deleted %s successfully\n", FILENAME); +} else { + printf ("There was a problem deleting %s\n", FILENAME); +} +</verb> +</descrip> +</quote> + + +<sect1>utoa<label id="utoa"><p> + +<quote> +<descrip> +<tag/Function/Convert an unsigned integer into a string. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ utoa (unsigned val, char* buf, int radix);/ +<tag/Description/<tt/itoa/ converts the unsigned integer <tt/val/ into a string +using <tt/radix/ as the base. +<tag/Limits/<itemize> +<item>There are no provisions to prevent a buffer overflow. +<item>The function is non standard, so it is not available in strict ANSI mode. +You should probably use <tt/sprintf/ instead. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="atoi" name="atoi">, +<ref id="atol" name="atol">, +<ref id="itoa" name="itoa">, +<ref id="ltoa" name="ltoa">, +<ref id="ultoa" name="ultoa"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>vcprintf<label id="vcprintf"><p> + +<quote> +<descrip> +<tag/Function/Formatted output to the console. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/int __fastcall__ vcprintf (const char* format, va_list ap);/ +<tag/Description/The arguments specified as a <tt/va_list/ are converted to +text where necessary and formatted according to the format string given. The +resulting string is output to the console. <tt/vcprintf/ supports the same +format specifiers as <tt/vprintf/. <!-- <tt/<ref id="vprintf" name="vprintf">/. --> +<tag/Limits/<itemize> +<item>Like all other <tt/conio/ output functions, <tt/vcprintf/ distinguishes +between <tt/\r/ and <tt/\n/. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="cprintf" name="cprintf">, +<ref id="cputc" name="cputc">, +<ref id="cputcxy" name="cputcxy">, +<ref id="cputs" name="cputs">, +<ref id="cputsxy" name="cputsxy"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>videomode<label id="videomode"><p> + +<quote> +<descrip> +<tag/Function/Switch to either 40 or 80 column mode. +<tag/Header/<tt/<ref id="apple2enh.h" name="apple2enh.h">, +<ref id="c128.h" name="c128.h">/ +<tag/Declaration/<tt/unsigned __fastcall__ videomode (unsigned Mode);/ +<tag/Description/Switch to 40 or 80 column mode depending on the argument. If +the requested mode is already active, nothing happens. The old mode is returned +from the call. +<tag/Limits/<itemize> +<item>The function is specific to the C128 and enhanced Apple //e. +<item>This function replaces <ref id="toggle_videomode" +name="toggle_videomode">. +<item>The function is only available as fastcall function, so it may only be +used in presence of a prototype. +</itemize> +<tag/Availability/C128 and enhanced Apple //e +<tag/See also/ +<ref id="fast" name="fast">, +<ref id="slow" name="slow">, +<ref id="toggle_videomode" name="toggle_videomode"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>wherex<label id="wherex"><p> + +<quote> +<descrip> +<tag/Function/Return the current X position of the text mode cursor. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char wherex (void);/ +<tag/Description/The function returns the current X position of the text mode +cursor. Zero is returned for the leftmost screen position. +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoy" name="gotoy">, +<ref id="gotoxy" name="gotoxy">, +<ref id="wherey" name="wherey"> +<tag/Example/None. +</descrip> +</quote> + + +<sect1>wherey<label id="wherey"><p> + +<quote> +<descrip> +<tag/Function/Return the current Y position of the text mode cursor. +<tag/Header/<tt/<ref id="conio.h" name="conio.h">/ +<tag/Declaration/<tt/unsigned char wherey (void);/ +<tag/Description/The function returns the current Y position of the text mode +cursor. Zero is returned for the uppermost screen position. +<tag/Availability/cc65 +<tag/See also/ +<ref id="gotox" name="gotox">, +<ref id="gotoy" name="gotoy">, +<ref id="gotoxy" name="gotoxy">, +<ref id="wherex" name="wherex"> +<tag/Example/None. +</descrip> +</quote> + + +</article> diff --git a/doc/geos.sgml b/doc/geos.sgml new file mode 100644 index 000000000..8a5a948a1 --- /dev/null +++ b/doc/geos.sgml @@ -0,0 +1,1662 @@ +<!doctype linuxdoc system> + +<article> + +<!-- Title information --> + +<title>GEOSLib docs +<author>Maciej Witkowiak, <htmlurl url="mailto:ytm@elysium.pl" name="ytm@elysium.pl"> +<date>v1.5, 26.12.1999, 2000, 2001, 2002, 2003, 2005 +<abstract> +This is the documentation of cc65's GEOSLib, but information contained here may be also +useful for writing GEOS applications in general. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Introduction +<p> +As we all know that the best computers in the world are the C64 and C128. They have their GUI too - +the excellent GEOS. GEOS seems very difficult and cryptic for many people, from programmer's point +of view. That's not true. The designers of GEOS created a flexible and powerful system, which +is easy to use and program. +<p> +Coding GEOS in C? That's something new. It is possible now - with Ulrich von Bassewitz's cc65 +package and my GEOSLib you are able to create GEOS applications in no time. +<p> +GEOSLib supports a subset of the standard cc65 libraries. Whenever possible native Kernal functions +are used (e.g. <tt/memset/ is an alias for <tt/FillRam/), however not all are supported. E.g. +string functions like <tt/strcmp/, <tt/strcpy/ are doubled with native <tt/CmpString/, +<tt/CopyString/ because the latter can handle only 256 byte strings. Keep this in mind when +you write your program. If you don't need long strings simply use functions from the Kernal, +the resulting code will be smaller. +<p> +<tt/dio/ - direct disk access is available, but you might have problems with devices other +than 1541, 1571 or 1581. RAM drives emulating these should work. +<p> +<tt/conio/ - simple console input-output is available for command line applications. +This implementation assumes that one character does fit in 8x8 cell, so output with +default BSW font, which is has 9 points, might be a bit messy. There is no color support in +GEOS 2.0 so color functions are disabled. Both 40 and 80 column modes are supported +and automatically detected. +<p> +<tt/tgi/ - TGI driver for GEOS that supports both 40 and 80 column modes but mode can not be +changed between <tt/tgi_init/ and <tt/tgi_done/. +<p> +<tt/joy/ - JOY driver for GEOS that supports only joystick, not current pointing device. +<p> +It is safe to use these standard includes and their contents: +<tt/assert.h, conio.h, dio.h, errno.h, em.h, geos.h, joystick.h, modload.h, mouse.h, stdlib.h, string.h, tgi.h, time.h/ +<p> +For <tt/time.h/ functions <tt/systime()/ and <tt/clock()/ note that the resolution is one second. +<p> +Functions from the headers above are either standard C library functions or cc65-specific, in +either case they are not GEOS specific and so they are not described here. +<p> +I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best +available code (well, the best as for machine :-). Many of the <tt/void foo (void)/ functions are +just raw calls to the Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you +can find many definitions of standard GEOS locations. Access to these addresses is optimized by +cc65 to simple <tt/lda/ and <tt/sta/. Don't be afraid to use C syntax. + +<sect1>Requirements +<p> +You don't need a C64 or C128 for development. The only hardware requirement is a PC capable of +running cc65. You do however need C64 or C128 emulator and GEOS disk images (.d64) to test your +programs. + +The software needed: +<itemize> + <item><em/cc65/ Excellent package containing a C crosscompiler, a crossassembler and a linker, you + can get it from: <htmlurl url="http://www.cc65.org/" + name="http://www.cc65.org/"> + <item><em/VICE/ This is a portable C64, C128 and few other Commodore computers emulator, you + can obtain it from: <htmlurl url="http://www.viceteam.org/" + name="http://www.viceteam.org/">. The VICE package contains the + c1541 program that is able to convert/unconvert GEOS files to disk images. + <item><em/The Star Commander/ This tool is only for DOS. You will need it for transferring + object files from a PC to a 1541. There's also one important ability of this + tool - it automatically un-converts .cvt files into GEOS native format on + disk image files. Check out: <htmlurl url="http://sta.c64.org/sc.html" + name="http://sta.c64.org/sc.html"> + <item><em/cbm4linux/ A Linux kernel module that allows for communication with a 1541 and + other Commodore IEC bus drives. It can be a replacement for Star Commander if + you only want to transfer files to a disk and unconvert using GEOS program for + this purpose. Check out: <htmlurl url="http://www.lb.shuttle.de/puffin/cbm4linux/" + name="http://www.lb.shuttle.de/puffin/cbm4linux"> +</itemize> +<p> +VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only +needs cc65. +<p> +<em/Update:/ starting from v2.5.0 GEOSLib is a part of the cc65 package as its GEOS support library. + +<sect1>Legal +<p> +I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's +Reference Guide and BSW for GEOS. +<p> +GEOSLib is covered by the same license as cc65. You can find the whole text +among documentation. I would really appreciate if you would like to send me +your comments, suggestions, questions, changes, bug reports etc. I will also +appreciate if you will just give me a sign that you are using GEOSLib - not +especially something big and important, mail me even if you are just playing +with it. +<p> +You can send postcards with hellos to: +<p> +Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW +<p> +POLAND +<p> +e-mail: <tt/ytm@elysium.pl/ + +<sect>What do you have and what to do with it? +<p> +This chapter describes some rules you ought to obey, and how to use GEOSLib. + +<sect1>Usage +<p> +Apart from this file, which merely describes only standard GEOS library +functions, you should read the <tt/grc65/ (GEOS resource compiler) documentation. +There is information about necessary resource files (each GEOS application +needs at least one) and the build process - what should be done and in what +order. Please also read the cc65 documentation on how to compile C, assembler +and link everything together. +<p> +All in all, you just need to place +<tscreen><verb> +#include <geos.h> +</verb></tscreen> +at the top of your source. +<p> +As a general rule read the sources of the example programs and read the headers. +These are the most reliable sources of knowledge ;-). You will also find there +many C macros representing various arguments passed to the functions. Please use +them. You will find your sources easier to understand, and it will be easier +to find bugs. +<p> +All types used in GEOSLib are <tt/unsigned/. +<p> +Screen coordinates are given in pixels unless stated differently. + +<sect1>Notes on style +<p> +Contrary to a typical GEOS assembly program which has a main function called after loading that +setups the screen, menus, icons etc. exiting from the <tt/main/ function in C is equivalent to +calling <tt/exit()/. These two are the only safe methods of terminating applications. DO NOT +USE <tt/EnterDeskTop/! Your data may be lost as library destructors and functions registered +with <tt/atexit/ are not called. +<p> +For GEOS GUI applications the recommended program structure is to have everything initialized +in the <tt/main/ function and at the end of it a call to the <tt/MainLoop()/ function. WARNING! This +function never returns, any code between <tt/MainLoop();/ and the end of <tt/main/ will not +be executed. You have to call <tt/exit()/ explicitly somewhere in your code (e.g. in a menu +handler or via DialogBox action). +<p> +Whenever possible use definitions from <tt/gsym.h/. The resulting code is translated by cc65 into +series of <tt/lda/ and <tt/sta/, so you can't do it better :-). +<p> +Don't hesitate to use library functions. Everything was written with size and speed in mind. In +fact many calls are just redirections to the GEOS Kernal which results in a simple <tt/jsr/. +<p> +The <tt/main/ function receives the standard <tt/argc/ and <tt/argv/ parameters. There are +always either 1 or 3 parameters. The DOS application name is always set as <tt/argv[0]/. +If present, <tt/argv[1]/ and <tt/argv[2]/ will be set to the data filename and data diskname (it only +works if the user double-clicks on a data file associated with your application). Note that it is up +to your application to determine which of the available (up to four) disk drives has the disk +with given diskname inside. If this fails your program should ask to insert the proper disk into +one of available drives. +<p> +You might wonder why I have chosen a sometimes weird order of arguments in functions. I just +wanted to avoid unnecessary pushing and popping of arguments from the stack because cc65 can pass a single +<tt/unsigned int/ through CPU registers. +<p> +Do not try to compile in strict ANSI mode. The library uses cc65 extensions which are not available in +ANSI. +<p> +It is possible to use dynamically loaded modules, three such modules are provided: +A GEOS TGI driver, a GEOS EMD driver (for VDC extended memory) and a GEOS JOY driver. +Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special +recommendations, read the cc65 documentation about modules and the demo programs source code. + +<sect>Library Functions +<p> +Functions here are sorted more or less in the way they appear in the header files. This way I am able +to keep functions covering similar tasks near each other. All function names are identical to those +from the <tt/geosSym/ file provided with the GeoProgrammer package. Only my extensions to <tt/geosSym/ +are covered by new names, but I tried to keep them in the naming convention. + +<sect1>Graphics +<p> +This section covers the drawing package of GEOS along with text output routines. + +<sect2>SetPattern +<p> +<tt/void SetPattern (char pattern)/ +<p> +This function sets the current pattern to the given. There are 32 different patterns in GEOS. You can +see them together in the filling box in GeoPaint. + +<sect2>GraphicsString +<p> +<tt/void GraphicsString (char *myGString)/ +<p> +One of the more powerfull routines of GEOS. This function calls other graphic functions depending +on the given command string. See the structures chapter for a more detailed description. + +<sect2>Rectangle functions +<p> +Parameters to those functions are grouped in the <tt/struct window drawWindow/. To speed up things and +reduce overhead this structure is bound to zero page locations, where all rectangle functions +expect their parameters. You can modify the data directly (e.g. <tt/drawWindow.top=10/) or via the +<tt/InitDrawWindow/ function. Contents of <tt/drawWindow/ are guaranteed not to change when only +using graphics functions. In other cases you should keep your data in separate <tt/struct window/ +and use <tt/InitDrawWindow/ before the first call to one of the rectangle functions. + +<sect3>InitDrawWindow +<p> +<tt/void InitDrawWindow (struct window *myWindow)/ +<p> +This function only copies the contents of <tt/myWindow/ into the system area of <tt/drawWindow/. Use it +if for some reason you have to keep your window data out of the zero page space. + +<sect3>Rectangle +<p> +<tt/void Rectangle (void)/ +<p> +This draws on screen a rectangle filled with the current pattern. + +<sect3>FrameRectangle +<p> +<tt/void FrameRectangle (char pattern)/ +<p> +This one draws a frame with the given bit pattern (not a pattern from the GEOS palette). + +<sect3>InvertRectangle +<p> +<tt/void InvertRectangle (void)/ +<p> +Just as the name says... + +<sect3>ImprintRectangle and RecoverRectangle +<p> +<tt/void ImprintRectangle (void)/ +<p> +<tt/void RecoverRectangle (void)/ +<p> +These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/) the +backbuffer of the screen. For example when drawing a new menu box GEOS first uses +<tt/ImprintRectangle/ to save the area under the box, and restores it by <tt/RecoverRectangle/ upon +destroying the menu. + +<sect2>Line Functions +<p> +The GEOS drawing package is optimized so there are different functions for drawing vertical and +horizontal lines. + +<sect3>HorizontalLine +<p> +<tt/void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)/ +<p> +This function draws a horizontal line using the given pattern. Note that <tt/pattern/ is not a pattern +number as set in <tt/SetPattern/ but a true bit pattern. + +<sect3>InvertLine +<p> +<tt/void InvertLine (char y, unsigned xStart, unsigned xEnd)/ +<p> +There is only a horizontal version. + +<sect3>RecoverLine +<p> +<tt/void RecoverLine (char y, unsigned xStart, unsigned xEnd)/ +<p> +This function recovers a single line. It is utilized by <tt/RecoverRectangle/. See its description +for more details. + +<sect3>VerticalLine +<p> +<tt/void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)/ +<p> +This function draws a vertical line using the given pattern. Note that <tt/pattern/ is not a pattern +number as set in <tt/SetPattern/ but a true bit pattern. + +<sect3>DrawLine +<p> +<tt/void DrawLine (char mode, struct window *myWindow)/ +<p> +The <tt/top/ parameters of <tt/struct window/ describe the starting point of the line, while +<tt/bottom/ ones are for the ending point. If <tt/mode/ is <tt/DRAW_DRAW/ then the current pattern from +<tt/SetPattern/ is used for drawing. If <tt/mode/ is <tt/DRAW_ERASE/ then the line is erased from the +screen. If <tt/mode/ is <tt/DRAW_COPY/ then the line is copied from/to back/frontbuffer, according to +the <tt/dispBufferOn/ setting. + +<sect2>Point Functions +<p> +The parameters to these two functions are passed by a pointer to an own <tt/struct pixel/ filled with +proper values. + +<sect3>DrawPoint +<p> +<tt/void DrawPoint (char mode, struct pixel *myPixel)/ +<p> +Depending on <tt/mode/ (see <tt/DrawLine/) draws/erases/copies a single point +on the screen. + +<sect3>TestPoint +<p> +<tt/char TestPoint (struct pixel *myPixel)/ +<p> +This function tests if the given pixel is set and returns <tt/true/ (non-zero) or <tt/false/ (zero). + +<sect2>Character and string output + +<sect3>PutChar +<p> +<tt/void PutChar (char character, char y, unsigned x)/ +<p> +This function outputs a single character using the current style and font to the screen. + +<sect3>PutString +<p> +<tt/void PutString (char *myString, char y, unsigned x)/ +<p> +Same as <tt/PutChar/ except the fact that you can output a whole <tt/NULL/-terminated string. +See <tt/ggraph.h/ for the list of tokens that you can also place in the string - like <tt/CBOLDON/ or +<tt/COUTLINEON/. + +<sect3>PutDecimal +<p> +<tt/void PutDecimal (char parameter, unsigned value, char y, unsigned x)/ +<p> +This function converts <tt/value/ to its decimal representation and outputs it to the screen. +The <tt/parameter/ is the field width in pixels (range 1-31) and the mode bits. Depending on them +the string can be filled with zeroes (the string is always 5 characters long) or not and left or right +justified to the given pixel. See <tt/ggraph.h/ for predefined values for <tt/parameter/. + +<sect2>Font Handling + +<sect3>GetCharWidth +<p> +<tt/char GetCharWidth (char character)/ +<p> +This function returns the real width (in pixels) of the given character with the current font. It can be used +for counting the length of a string on the screen, allowing for indentation or justification. + +<sect3>LoadCharSet +<p> +<tt/void LoadCharSet (struct fontdesc *myFont)/ +<p> +This function forces GEOS to use the given font. <tt/myFont/ should be casted from a +pointer to the start of the area where a record from a font file (VLIR structure) was loaded. + +<sect3>UseSystemFont +<p> +<tt/void UseSystemFont (void)/ +<p> +This function forces GEOS to use the built-in BSW font. + +<sect2>Bitmap handling +<p> +I'm not quite sure how these functions are working (except <tt/BitmapUp/) so you should +probably look into the library sources and compare it with your knowledge. Please let me know +if something is wrong or broken. + +<sect3>BitmapUp +<p> +<tt/void BitmapUp (struct iconpic *myPic)/ +<p> +This function unpacks the bitmap and places it on the screen - just as you set it in the +<tt/struct iconpic/ pointer which you pass. See <tt/gstruct.h/ for a description of this +structure. Note that you can only use packed GEOS bitmaps - a simple Photo Scrap is in this format. + +<sect3>BitmapClip +<p> +<tt/void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)/ +<p> +This function acts similar to <tt/BitmapUp/ but you can also define which parts of the bitmap are +to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap, +and the number of rows to skip from the top if it. + +<sect3>BitOtherClip +<p> +<tt/void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop, + struct iconpic *myPic)/ +<p> +Similar to the previous one with some extension. <tt/proc1/ is called before reading a byte (it +returns in .A the next value), and <tt/proc2/ is called every time the parser reads a byte which is +not a piece of a pattern (byte of code greater than 219). Both procedures should be written +separately in assembler and declared as <tt/__fastcall__/ returning char. + +<sect1>Menus and Icons +<p> +Here you will find information about functions related with menus and icons. + +<sect2>Menus +<p> +Menus are essential for a GUI. GEOS can handle only one menu at a time, but each menu can call +another one, which results in a submenu tree. There can be up to 8 menu levels, each one with up +to 32 items. +<p> +Menus are initialized with <tt/DoMenu/ and then the Kernal takes care of everything. Your code +(called from an event handler) should be a function without parameters, returning void. You should +use <tt/DoPreviousMenu/ or <tt/GotoFirstMenu/ at least once in its code to have the screen clean. + +<sect3>DoMenu +<p> +<tt/void DoMenu (struct menu *myMenu)/ +<p> +This function initializes the GEOS menu processor and exits. See <tt/DoMenu structure/ for more +information about it. Know that many GEOS applications just initialize the screen, menu and +exit to the main Kernal loop, this proves the power of <tt/DoMenu/. + +<sect3>ReDoMenu +<p> +<tt/void ReDoMenu (void)/ +<p> +This simply redraws the menu at the lowest level. It works like calling <tt/DoMenu/ again with +the same parameters. + +<sect3>RecoverMenu +<p> +<tt/void RecoverMenu (void)/ +<p> +This function erases the current menu from the screen. It doesn't change the menu level. + +<sect3>RecoverAllMenus +<p> +<tt/void RecoverAllMenus (void)/ +<p> +This calls <tt/RecoverMenu/ and erases all menus from the screen. Then the menu level is +set to 0 (topmost). + +<sect3>DoPreviousMenu +<p> +<tt/void DoPreviousMenu (void)/ +<p> +This functions causes the menu processor to go back one menu level. You should use it in menu +handler code to have the screen clean. + +<sect3>GotoFirstMenu +<p> +<tt/void GotoFirstMenu (void)/ +<p> +This one jumps back to the topmost menu. If there is only a menu and one submenu it works the +same as <tt/DoPreviousMenu/. + +<sect2>Icon Functions +<p> +Icons are working similar to menus except the fact that there is only one level. Icons are +defined as a screen area filled with a bitmap, but if you would setup icons and erase the +screen they would still be active and clicking in the place where formerly an icon was would cause +an effect. Similarly if you would setup icons and then turn them off with <tt/ClearMouseMode/ +the bitmap would still be on the screen but clicking on it would not cause any action. +There is only one, but powerful icon function. + +<sect3>DoIcons +<p> +<tt/void DoIcons (struct icontab *myIconTab)/ +<p> +This function initializes all icons that are present on the screen at once. For more information +look at the <tt/Icons/ chapter in this manual. + +<sect1>DialogBoxes +<p> +This chapter covers the most powerful GEOS user interface function - <tt/DoDlgBox/. + +<sect2>GEOS standard + +<sect3>DoDlgBox +<p> +<tt/char DoDlgBox (char *dialogString)/ +<p> +This function returns one byte. It can be the value of one of six standard icons (see <tt/gdlgbox.h/) +or whatever the closing routine passes. Register <tt/r0L/ also contains this value. +<p> +Read the structures chapter for the specs of the <tt/dialogString/. + +<sect3>RstrFrmDialogue +<p> +<tt/char RstrFrmDialogue/ +<p> +This function is called from within DoDlgBox event. It immediately closes the DialogBox and returns +the owner ID (or whatever caller has in the .A register). + +<sect2>GEOSLib extensions +<p> +To simplify the usage of DoDlgBox from C I wrote some helper functions - wrappers for DoDlgBox, +with predefined data. In one word - these are standard DialogBoxes you can see in almost every +GEOS application. + +<sect3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk +<p> +<tt/char DlgBoxYesNo (char *line1, char *line2)/ +<p> +<tt/char DlgBoxOkCancel (char *line1, char *line2)/ +<p> +<tt/void DlgBoxOk (char *line1, char *line2)/ +<p> +These function show two lines of text in a standard-sized DialogBox. You can read the code of the +pressed icon from the return value. E.g. for <tt/DlgBoxYesNo/ it can only be <tt/YES/ or <tt/NO/. +You can pass an empty string or NULL to get a blank line. + +<sect3>DlgBoxGetString +<p> +<tt/char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)/ +<p> +This function prompts the user to enter a string of at most <tt/strlen/ characters. It is returned +in <tt/string/. The two given lines of text are shown above the input line. Please remember +that there is also a <tt/CANCEL/ icon in the DialogBox and you should test if user confirmed his +input or gave up. The <tt/string/ is also shown so you can place a default input there or remember +to place <tt/NULL/ at start. + +<sect3>DlgBoxFileSelect +<p> +<tt/char DlgBoxFileSelect (char *class, char filetype, char *filename)/ +<p> +This routine is the standard file selector. It can return <tt/OPEN/, <tt/CANCEL/ or disk error +on reading the directory or opening the disk. +There is also a <tt/DISK/ icon shown, but it is handled internally. You pass as input parameters +<tt/filetype/ and a pointer to a string containing the first part of a file's class. If this string is +empty (<tt/NULL/ at the start), then all files with given filetype will be shown. +<p> +At present this file selector handles only first 16 files of given type and supports only one +(current) drive. + +<sect3>MessageBox +<p> +<tt/char MessageBox (char mode, const char *format, ...)/ +<p> +This function is a more general one. It works very much like <tt/printf/ in a +box. The only difference is the <tt/mode/ parameter which allows for placing +default icons (see <tt/gdlgbox.h/ for list of possible <tt/MB_/ values). +Any too wide text will be clipped to the size of the default window. If <tt/mode/ +is invalid or equal to <tt/MB_EMPTY/ then the window will be closed +after a click. Otherwise the user must choose an icon. +<p> +Note: Use it if you really need (or if you use it in many places) as +it adds quite amount of code to your program. +<p> +Note: the formatted text <em/cannot exceed/ 255 bytes in length, there is no check +for that. + +<sect1>Mouse, Sprites and Cursors +<p> +You will find here functions related to sprite and mouse drawing and handling. + +<sect2>Mouse related functions +<p> +These cover the mouse - as a general pointing device, but expect users to utilize as different devices +as a digital or analog joystick, a mouse, a lightpen or a koalapad (whatever it is). + +<sect3>StartMouseMode +<p> +<tt/void StartMouseMode (void)/ +<p> +This function initializes the mouse vectors - <tt/mouseVector/ and <tt/mouseFaultVec/, and then +calls <tt/MouseUp/. + +<sect3>ClearMouseMode +<p> +<tt/void ClearMouseMode (void)/ +<p> +This function disables all mouse activities - icons and menus stop to respond to mouse events, +but they are not cleared from the screen. + +<sect3>MouseUp and MouseOff +<p> +<tt/void MouseUp (void)/ +<p> +<tt/void MouseOff (void)/ +<p> +The first function turns the mouse pointer on. It appears on the next IRQ. The second one does +the opposite - it turns off the pointer, but its position is still updated by the input driver. + +<sect3>IsMseInRegion +<p> +<tt/char IsMseInRegion (struct window *myWindow)/ +<p> +This function tests if the mouse pointer is actually in the given range of the screen. See <tt/gsprite.h/ for +a description of the bits in the return values - they describe the position in detail. + +<sect2>Sprites +<p> +You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse +pointer and sprite 1 can be overwritten when using a text prompt. You don't have to worry about +40/80 column issues because GEOS128 has a pretty good sprite emulator for the VDC. + +<sect3>DrawSprite +<p> +<tt/void DrawSprite (char sprite, char *mySprite)/ +<p> +This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which +is copied to the system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Hardware sprite registers are +not initialized and the sprite is not yet visible. + +<sect3>PosSprite +<p> +<tt/void PosSprite (char sprite, struct pixel *myPixel)/ +<p> +This function positions the sprite on the screen. The given coordinates are screen ones - they are +converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your +sprite off the left or top to the screen. + +<sect3>EnablSprite and DisablSprite +<p> +<tt/void EnablSprite (char sprite)/ +<p> +<tt/void DisablSprite (char sprite)/ +<p> +These two functions are responsible for making the sprite visible or not. + +<sect2>Cursors and Console + +<sect3>InitTextPrompt +<p> +<tt/void InitTextPrompt (char height)/ +<p> +This function initializes sprite 1 for a text prompt with given <tt/height/. This parameter can be in +range 1-48. + +<sect3>PromptOn and PromptOff +<p> +<tt/void PromptOn (struct pixel *myPixel)/ +<p> +<tt/void PromptOff (void)/ +<p> +The first function places a text prompt in given place and enables blinking. +The second one is pretty self-explanatory. + +<sect3>GetNextChar +<p> +<tt/char GetNextChar (void)/ +<p> +This function gets the next character from the keyboard queue. If the queue is empty it returns +<tt/NULL/, otherwise you receive the true ASCII code of a character or the value of a special (function) +key. See <tt/gsprite.h/ for the list of them. + +<sect1>Disk +<p> +This chapter covers rather low-level disk routines. You should use them with care, because +you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various +devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be +dangerous. +<p> +For some purposes you might consider using the <tt/dio.h/ interface to disk access. It is native. +<p> +All GEOS disk functions return an error code in the X register. In some cases this is returned by the +GEOSLib function (if its type is <tt/char/), but in all cases the last error is saved in the <tt/__oserror/ +location. If it is nonzero - an error occured. See <tt/gdisk.h/ for the list of possible errorcodes. +You need to include <tt/errno.h/ to get <tt/__oserror/, together with the standard <tt/errno/. The +latter gives less verbose, but still usable information and can be used with <tt/strerror/. +Probably you will get more information using <tt/_stroserror/ in a similar way. +<p> +For passing parameters use almost always a pointer to your data e.g. <tt/ReadBuff (&myTrSe)/. + +<sect2>Buffer functions +<p> +These functions take a single data sector (256 bytes) to read or write on the disk. + +<sect3>ReadBuff and Writebuff +<p> +<tt/char ReadBuff (struct tr_se *myTrSe)/ +<p> +<tt/char WriteBuff (struct tr_se *myTrSe)/ +<p> +These functions read and write a sector placed at <tt/diskBlkBuf/. + +<sect3>GetBlock and ReadBlock +<p> +<tt/char GetBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +<tt/char ReadBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +These two functions read a single block directly to the 256 byte array placed at <tt/buffer/. +The difference between them is that <tt/GetBlock/ initializes TurboDos in the drive if it was not +enabled. <tt/ReadBlock/ assumes that it is already enabled thus being slightly faster. + +<sect3>PutBlock, WriteBlock, VerWriteBlock +<p> +<tt/char PutBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +<tt/char WriteBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +<tt/char VerWriteBlock (struct tr_se *myTrSe, char *buffer)/ +<p> +Similar to previous but needed for writing the disk. <tt/VerWriteBlock/ verifies the data after +writing. In case of an error five tries are attempted before an error code is returned. + +<sect2>Directory header +<p> +The functions described here operate on <tt/curDirHeader/ where the current disk header is stored. +On larger (than 1541) capacity drives the second part of the directory header is in <tt/dir2Head/. + +<sect3>GetPtrCurDkNm +<p> +<tt/void GetPtrCurDkNm (char *diskName)/ +<p> +This function fills the given character string with the name of current disk. It is converted to C +standard - the string is terminated with <tt/NULL/ character instead of code 160 as in Commodore DOS. +Note that the passed pointer must point to an array of at least 17 bytes. + +<sect3>GetDirHead and PutDirHead +<p> +<tt/char GetDirHead (void)/ +<p> +<tt/char PutDirHead (void)/ +<p> +These functions read and write the directory header. You should use <tt/GetDirHead/ before +using any functions described below, and you should use <tt/PutDirHead/ to save the changes on the +disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/. + +<sect3>CalcBlksFree +<p> +<tt/unsigned CalcBlksFree (void)/ +<p> +This function returns the number of free blocks on the current disk. It is counted using data in +<tt/curDirHead/ so you must initialize the disk before calling it. + +<sect3>ChkDskGEOS +<p> +<tt/char ChkDskGEOS (void)/ +<p> +This functions checks <tt/curDirHead/ for the GEOS Format identifier. It returns either true or false, +and also sets <tt/isGEOS/ properly. You must initialize the disk before using this. + +<sect3>SetGEOSDisk +<p> +<tt/char SetGEOSDisk (void)/ +<p> +This function initializes disk for use with GEOS. It sets the indicator in directory header and +allocates a sector for the directory of border files. You don't need to initialize the disk before +using. + +<sect3>FindBAMBit +<p> +<tt/char FindBAMBit (struct tr_se *myTrSe)/ +<p> +This function returns the bit value from the BAM (Block Allocation Map) for the given sector. The bit is +set if the sector is free to use. The returned value is always zero if the sector is already allocated. +In fact, this function could be used in a following way: +<tscreen><verb> +#define BlockInUse FindBAMBit +... +if (!BlockInUse(&myTrSe)) { +... block not allocated ... +} +</verb></tscreen> +<p> +Anyway, I feel that this function is too low-level. + +<sect3>BlkAlloc and NxtBlkAlloc +<p> +<tt/char BlkAlloc (struct tr_se output[&rsqb, unsigned length)/ +<p> +<tt/char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[&rsqb, unsigned length)/ +<p> +Both functions allocate enough disk sectors to fit <tt/length/ bytes in them. You +find the output in <tt/output/ which is a table of <tt/struct tr_se/. The last entry will have the +track equal to 0 and sector equal to 255. The simplest way of using them is to use +predefined space in the GEOS data space and pass <tt/fileTrScTab/, which is a predefined table. +<p> +The difference between those two is that <tt/NextBlkAlloc/ starts allocating from the given sector, +and <tt/BlkAlloc/ starts from the first nonused sector. +<p> +You need to use <tt/PutDirHead/ later to save any changes in BAM. + +<sect3>FreeBlock +<p> +<tt/char FreeBlock (struct tr_se *myTrSe)/ +<p> +Simply deallocates a block in the BAM. You need to update the BAM with <tt/PutDirHead/. + +<sect3>SetNextFree +<p> +<tt/struct tr_se SetNextFree (struct tr_se *myTrSe)/ +<p> +This function finds the first free sector starting from given track and sector and allocates it. +It might return the same argument if the given block is not allocated. I wanted it to be type +clean, but this made the usage a bit tricky. To assign a value to your own <tt/struct tr_se/ you have to +cast both variables to <tt/unsigned/. E.g. +<tscreen><verb> +struct tr_se myTrSe; +... +(unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe); +</verb></tscreen> +<p> +In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/. +<p> +Note: you <em/must/ use casting to have the correct values. + +<sect2>Low-level disk IO +<p> +Functions described here are more usable in Kernal or drivers code, less common in applications, +but who knows, maybe someone will need them. + +<sect3>EnterTurbo, ExitTurbo, PurgeTurbo +<p> +<tt/void EnterTurbo (void)/ +<p> +<tt/void ExitTurbo (void)/ +<p> +<tt/void PurgeTurbo (void)/ +<p> +These functions are the interface to the GEOS TurboDos feature which makes slow Commodore drives a bit +more usable. <tt/EnterTurbo/ enables TurboDos unless it is already enabled. If not, then you will +have to wait a bit to transfer the TurboDos code into disk drive RAM. <tt/ExitTurbo/ disables TurboDos. +This is useful for sending some DOS commands to a drive e.g. for formatting. Note that before any +interaction with the Kernal in ROM you have to call <tt/InitForIO/. You don't have to worry about speed. +<tt/EnterTurbo/ will only enable TurboDos (no code transfer) if TurboDos was disabled with +<tt/ExitTurbo/. <tt/PurgeTurbo/ acts differently from <tt/ExitTurbo/ - it not only disables TurboDos, +but also removes it from drive RAM (not quite true, but it works like that). After using +<tt/PurgeTurbo/ the next call to <tt/EnterTurbo/ will reload drive RAM. + +<sect3>ChangeDiskDevice +<p> +<tt/char ChangeDiskDevice (char newDevice)/ +<p> +This function changes the device number of the current device (in fact drives only) to the given one. It is +usable for swapping drives. There's no check if the given <tt/newDevice/ already exist, so if you want +to change the logical number of drive 8 to 9 and you already have a drive number 9 then GEOS will probably +hang on disk access. Use safe, large numbers. Note that the safe IEC range is 8-30. + +<sect2>Disk Initialization +<p> +GEOS has two functions for initialization ('logging in' as they say on CP/M) of a disk. +<sect3>OpenDisk +<p> +<tt/char OpenDisk (void)/ +<p> +This function initializes everything for a new disk. It loads and enables TurboDos if needed. +Then the disk is initialized with <tt/NewDisk/. Next, <tt/GetDirHead/ initializes <tt/curDirHead/. +Disk names are compared and if they differ then the disk cache on REU is cleared. Finally the format is +checked with <tt/ChkDkGEOS/ and the disk name is updated in the internal tables. + +<sect3>NewDisk +<p> +<tt/char NewDisk (void)/ +<p> +This function is similar to the DOS command I. It clears the REU cache and enables TurboDos if needed. + +<sect1>Files +<p> +This section covers the GEOS file interface. + +<sect2>Directory handling +<p> +The functions described here are common for SEQ and VLIR structures. + +<sect3>Get1stDirEntry and GetNxtDirEntry +<p> +<tt/struct filehandle *Get1stDirEntry (void)/ +<p> +<tt/struct filehandle *GetNxtDirEntry (void)/ +<p> +These two functions are best suited for scanning the whole directory for particular files. Note that +the returned filehandles describe all file slots in the directory - even those with deleted files. +The return value can be obtained by casting both sides to <tt/unsigned/ - as in the <tt/SetNextFree/ +function or read directly after a call to those two functions from <tt/r5/. The current sector number +is in <tt/r1/ and the sector data itself is in <tt/diskBlkBuf/. + +<sect3>FindFile +<p> +<tt/char FindFile (char *fName)/ +<p> +This function scans the whole directory for the given filename. It returns either 0 (success) or 5 +(FILE_NOT_FOUND, defined in <tt/gdisk.h/) or any other fatal disk read error. After a successful +<tt/FindFile/ you will have <tt/struct filehandle/ at <tt/dirEntryBuf/ filled with the file's data and +other registers set as described in <tt/GetNxtDirEntry/. + +<sect3>FindFTypes +<p> +<tt/char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)/ +<p> +This function scans the directory and fills a table at <tt/buffer/ with <tt/char [17]/ entries. +<tt/fType/ is the GEOS type of the searched files and <tt/classTxt/ is a string for the Class field in the file +header. Class matches if the given string is equal or shorter than that found in the file's header block. +If you want just to find all files with the given GEOS type you should pass an empty string or <tt/NULL/ as +<tt/classTxt/. Be warned that for searching <tt/NON_GEOS/ files you must pass <tt/NULL/ as <tt/classTxt/. +<tt/fMaxNum/ is the maximal number of files to find, thus the <tt/buffer/ must provide an area of size +equal to <tt/17 * fMaxNum/. This function returns the number of found files, ranging from 0 to number +passed as <tt/fMaxNum/. The return value can be also restored from <tt/r7H/. + +<sect3>DeleteFile +<p> +<tt/char DeleteFile (char *fName)/ +<p> +This function deletes a file by its name. It works for SEQ and VLIR files. + +<sect3>RenameFile +<p> +<tt/char RenameFile (char *oldName, char *newName)/ +<p> +I think it is obvious... + +<sect3>GetFHdrInfo +<p> +<tt/char GetFHdrInfo (struct filehandle *myFile)/ +<p> +This function loads the file header into the <tt/fileHeader/ buffer. Using after e.g. <tt/FindFile/ +you can pass the address of <tt/dirEntryBuf/. + +<sect2>Common and SEQ structure +<p> +Functions described here are common for SEQ and VLIR structures because the arguments passed are the +starting track and sector which may point either to the start of a chain for VLIR or the data for SEQ. + +<sect3>GetFile +<p> +<tt/char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)/ +<p> +This routine loads and runs a given file <tt/fname/. The file must be one of following types: +<tt/SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER,/ or <tt/INPUT_DEVICE/. The execution +address is taken from the file header. If it is zero, then the file is only loaded. Only the first chain +from VLIR files is loaded. If <tt/flag/ has bit 0 set then the load address is taken from <tt/loadaddr/ +and not from the file header. In this case <tt/APPLICATION/ files will be only loaded, not executed. +This does not apply to <tt/DESK_ACC/. If either bit 6 or 7 of <tt/flag/ are set, then 16 bytes from +<tt/datadname/ are copied to <tt/dataDiskName/ and 16 bytes from <tt/datafname/ go to <tt/dataFileName/ +thus becoming parameters for the new application. Pass <tt/NULL/ for any unused parameter. + +<sect3>ReadFile +<p> +<tt/char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)/ +<p> +This function reads at most <tt/fLength/ bytes into <tt/buffer/ from chained sectors starting at +<tt/myTrSe/. + +<sect3>ReadByte +<p> +<tt/char ReadByte (void)/ +<p> +This function returns the next byte from a file. Before the first call to it you must load <tt/r5/ +with <tt/NULL/, <tt/r4/ with the sector buffer address and <tt/r1/ with the track and sector of the +first block of a file. +Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/. These registers must be preserved between +calls to <tt/ReadByte/. +<p> +The returned value is valid only if there was no error. The end of file is marked as <tt/BFR_OVERFLOW/ +in <tt/__oserror/, this is set when trying to read one byte after the end of file, in this case the +returned value is invalid. + +<sect3>SaveFile +<p> +<tt/char SaveFile (char skip, struct fileheader *myHeader)/ +<p> +<tt/SaveFile/ will take care of everything needed to create a GEOS file, no matter if VLIR of SEQ +structure. All you need to do is to place the data in the proper place and prepare a header which will +contain all information about a file. The <tt/skip/ parameter says how many directory pages you +want to skip before searching for a free slot for the directory entry. In most cases you will put +<tt/0/ there. +<p> +You have to declare a <tt/struct fileheader/ and fill it with proper values. There is only one +difference - the first two bytes which are a link to a nonexistent next sector are replaced by a +pointer to the DOS filename of the file. +<p> +When saving sequential files the two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/ +and <tt/fileheader.end_address/. + +<sect3>FreeFile +<p> +<tt/char FreeFile (struct tr_se myTable[])/ +<p> +This function deallocates all sectors contained in the passed table. + +<sect3>FollowChain +<p> +<tt/char FollowChain(struct tr_se *myTrSe, char *buffer)/ +<p> +This function fills a <tt/struct tr_se/ table at <tt/buffer/ with the sector numbers for a chain of +sectors starting with <tt/myTrSe/. You can pass such data (<tt/buffer/) to e.g. <tt/FreeFile/. + +<sect2>VLIR structure +<p> +Here is information about VLIR files (later called RecordFiles) and functions. +<p> +A VLIR structure file consists of up to 127 SEQ-like files called records. Each record is like one +SEQ structure file. Records are grouped together, described by a common name - the VLIR file name and +an own number. Each record pointed to by its number is described by the starting track and sector numbers. +VLIR structures allow records to be empty (<tt/tr_se/ of such record is equal to <tt/{NULL,$ff}/), +or even non-exist (<tt/{NULL,NULL}/). Any other numbers represent the starting track and sector of +a particular file. +<p> +In GEOS there can be only one file opened at a time. Upon opening a VLIR file some information +about it is copied into memory. You can retrieve the records table at <tt/fileTrScTab/ (table of +128 <tt/struct tr_se/) and from <tt/VLIRInfo/ (<tt/struct VLIR_info/. +E.g. the size of whole VLIR file can be retrieved by reading <tt/VLIRInfo.fileSize/. + +<sect3>OpenRecordFile +<p> +<tt/char OpenRecordFile (char *fName)/ +<p> +This function finds and opens a given file. An error is returned if the file is not found or if it is not +in VLIR format. Information in <tt/VLIRInfo/ is initialized. VLIR track and sector table is +loaded at <tt/fileTrScTab/ and will be valid until a call to <tt/CloseRecordFile/ so don't modify it. +You should call <tt/PointRecord/ before trying to do something with the file. + +<sect3>CloseRecordFile +<p> +<tt/char CloseRecordFile (void)/ +<p> +This function calls <tt/UpdateRecordFile/ and clears internal GEOS variables. + +<sect3>UpdateRecordFile +<p> +<tt/char UpdateRecordFile (void)/ +<p> +This function will check the <tt/VLIRInfo.fileWritten/ flag and if it is set, then <tt/curDirHead/ is +updated along with size and date stamps in the directory entry. + +<sect3>PointRecord +<p> +<tt/char PointRecord (char recordNumber)/ +<p> +This function will setup internal variables (and <tt/VLIRInfo.curRecord/) and return the track and +sector of the given record in <tt/r1/. Note that the data may not be valid (if the record is non-existing +you will get 0,0 and if it is empty - 255,0). + +<sect3>NextRecord and PreviousRecord +<p> +<tt/char NextRecord (void)/ +<p> +<tt/char PreviousRecord (void)/ +<p> +These two work like <tt/PointRecord/. Names are self-explanatory. + +<sect3>AppendRecord +<p> +<tt/char AppendRecord (void)/ +<p> +This function will append an empty record (pair of 255,0) to the current VLIR track and sector +table. It will also set <tt/VLIRInfo.curRecord/ to its number. + +<sect3>DeleteRecord +<p> +<tt/char DeleteRecord (void)/ +<p> +This function will remove the current record from the table, and move all current+1 records one place +back (in the table). Note that there's no BAM update and you must call <tt/UpdateRecordFile/ to +commit changes. + +<sect3>InsertRecord +<p> +<tt/char InsertRecord (void)/ +<p> +This function will insert an empty record in place of <tt/VLIRInfo.curRecord/ and move all following +records in the table one place forward (contents of <tt/VLIRInfo.curRecord/ after a call to <tt/InsertRecord/ +can be found in <tt/VLIRInfo.curRecord + 1/). + +<sect3>ReadRecord and WriteRecord +<p> +<tt/char ReadRecord (char *buffer, unsigned fLength)/ +<p> +<tt/char WriteRecord (char *buffer, unsigned fLength)/ +<p> +This function will load or save at most <tt/fLength/ bytes from the currently pointed record into or from +<tt/buffer/. + +<sect1>Memory and Strings +<p> +The functions covered in this section are common for the whole C world - copying memory parts and +strings is one of the main computer tasks. GEOS also has an interface to do this. These functions +are replacements for those like <tt/memset, memcpy, strcpy/ etc. from standard libraries. +If you are dealing with short strings (up to 255 characters) you should use these functions +instead of standard ones, e.g. <tt/CopyString/ instead of <tt/strcpy/. It will work faster. +<p> +However some of them have slightly different calling conventions (order of arguments to be specific), +so please check their syntax here before a direct replacement. +<p> +Please note that the memory areas described here as <em/strings/ are up to 255 characters (without +counting the terminating <tt/NULL/), and <em/regions/ can cover the whole 64K of memory. + +<sect2>CopyString +<p> +<tt/void CopyString (char *dest, char *src)/ +<p> +This function copies the string from <tt/src/ to <tt/dest/, until it reaches <tt/NULL/. The <tt/NULL/ +is also copied. + +<sect2>CmpString +<p> +<tt/char CmpString (char *s1, char *s2)/ +<p> +This function compares the strings <tt/s1/ to <tt/s2/ for equality - this is case sensitive, and both +strings have to have the same length. It returns either <tt/true/ (non-zero) or <tt/false/ (zero). + +<sect2>CopyFString and CmpFString +<p> +<tt/void CopyFString (char length, char *dest, char *src)/ +<p> +<tt/char CmpFString (char length, char *s1, char *s2)/ +<p> +These two are similar to <tt/CopyString/ and <tt/CmpString/ except the fact, that you provide +the length of the copied or compared strings. The strings can also contain several <tt/NULL/ +characters - they are not treated as delimiters. + +<sect2>CRC +<p> +<tt/unsigned CRC (char *src, unsigned length)/ +<p> +This function calculates the CRC checksum for the given memory range. I don't know if it is +compatible with standard CRC routines. + +<sect2>FillRam and ClearRam +<p> +<tt/void *FillRam (char *dest, char value, unsigned length)/ +<p> +<tt/void *ClearRam (char *dest, unsigned length)/ +<p> +Both functions are filling the given memory range. <tt/ClearRam/ fills with <tt/0s/, while +<tt/FillRam/ uses the given <tt/value/. Be warned that these functions destroy <tt/r0, r1 and +r2L/ registers. The functions are aliases for <tt/memset/ and <tt/bzero/, respectively. + +<sect2>MoveData +<p> +<tt/void *MoveData (char *dest, char *src, unsigned length)/ +<p> +This functions copies one memory region to another. There are checks for an overlap and the +non-destructive method is chosen. Be warned that this function destroys contents of the +<tt/r0, r1 and r2/ registers. This function is an alias for <tt/memcpy/. + +<sect2>InitRam +<p> +<tt/void InitRam (char *table)/ +<p> +This function allows to initialize multiple memory locations with single bytes or strings. +This is done with a <tt/table/ where everything is defined. See the structures chapter for a description of +<tt/InitRam's/ command string. + +<sect2>StashRAM, FetchRAM, SwapRAM, and VerifyRAM +<p> +<tt/void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ +<p> +<tt/void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ +<p> +<tt/void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ +<p> +<tt/ char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/ +<p> +These functions are the interface to a REU - Ram Expansion Unit. I think that they are self-explanatory. +You can check for REU presence by taking the value of <tt/ramExpSize/. You have to do it before +using any of these functions. + +<sect1>Processes and Multitasking +<p> +Weird? Not at all. GEOS has some limited multitasking ability. You can set up a chain of functions +called in specified intervals and you can put the main program to sleep without disturbing other +tasks and making the user interface unresponsive. + +<sect2>InitProcesses +<p> +<tt/void InitProcesses (char number, struct process *processTab)/ +<p> +This is the main initialization routine. After calling it processes are set up, but not +enabled. The parameters for <tt/InitProcesses/ are: +<itemize> + <item><tt/number/ - number of processes + <item><tt/processTab/ - a table of <tt/struct process/, with size equal to <tt/number/ +</itemize> +<p> +A single task is described by an entry in <tt/processTab/, it contains two values - a <tt/pointer/ to +the task function and a number of <tt/jiffies/ which describe the delay between calls to task. On PAL +systems there are 50 jiffies per second, while on NTSC there are 60. +<p> +The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and +if <tt/processTab/ would be too large it would overwrite existing data in GEOS space. +<p> +There's one important thing - the last entry in <tt/processTab/ has to be <tt/NULL,NULL/, so the +maximum size of <tt/processTab/ is equal to 21. +<p> +See the description of <tt/process/ structure for a more detailed discussion on this. + +<sect2>RestartProcess and EnableProcess +<p> +<tt/void RestartProcess (char processNumber)/ +<p> +<tt/void EnableProcess (char processNumber)/ +<p> +These two functions start the task counter. <tt/RestartProcess/ should be called for each process +after <tt/InitProcesses/, because it resets all flags and counters and it starts the counters. +<p> +<tt/RestartProcess/ enables the counters and sets their initial value to that given in <tt/processTab/. +<p> +<tt/EnableProcess/ forces the given process to execute by simulating the timer expiring. + +<sect2>BlockProcess and UnblockProcess +<p> +<tt/void BlockProcess (char processNumber)/ +<p> +<tt/void UnblockProcess (char processNumber)/ +<p> +<tt/BlockProcess/ disables the execution of the given process, but this does not disable the timers. +It means that if you call <tt/UnblockProcess/ before the timer runs out, the process will be executed. +<p> +<tt/UnblockProcess/ does the opposite. + +<sect2>FreezeProcess and UnfreezeProcess +<p> +<tt/void FreezeProcess (char processNumber)/ +<p> +<tt/void UnfreezeProcess (char processNumber)/ +<p> +<tt/FreezeProcess/ disables timer for given process. <tt/UnfreezeProcess/ does the opposite. +This is not equal to <tt/RestartProcess/ as timers are not reloaded with initial value. + +<sect2>Sleep +<p> +<tt/void Sleep (unsigned jiffies)/ +<p> +This function is a multitasking sleep - the program is halted, but it doesn't block other functions +e.g. callbacks from menus and icons. +The only argument here is the number of jiffies to wait until the app will wake up. It depends on the +video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively). +If you don't want to worry about it and need only full second resolution, call the standard +<tt/sleep/ function from <tt/unistd.h/. + +<sect1>System Functions + +<sect2>FirstInit +<p> +<tt/void FirstInit (void)/ +<p> +This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot +up. You shouldn't use this unless you know what you are doing. + +<sect2>InitForIO and DoneWithIO +<p> +<tt/void InitForIO (void)/ +<p> +<tt/void DoneWithIO (void)/ +<p> +These functions are called by some disk routines. You should call them only if you want to +do something with IO registers or call one of the Kernal ROM routines. Note that this is rather an +expensive way of turning off IRQs and enabling IO. + +<sect2>MainLoop +<p> +<tt/void MainLoop (void)/ +<p> +Returns control to the system. Any code between call to <tt/MainLoop/ and the end of current +function will never be executed. When in <tt/MainLoop/ the system waits for your action - using +icons, keyboard or menus to force some specific action from the program. You have to define +proper handlers before that. + +<sect2>EnterDeskTop +<p> +<tt/void EnterDeskTop (void)/ +<p> +This is an alias for <tt/exit(0)/ so you will never burn yourself. Anyway, you should not +use it. Always use <tt/exit()/ instead. Library destructors and functions registered with +<tt/atexit()/ are called. + +<sect2>ToBASIC +<p> +<tt/void ToBASIC (void)/ +<p> +This one is another way of terminating an application - forcing GEOS to shutdown and exit to BASIC. +I was considering whether to include it or not, but maybe someone will need it - which I doubt. +<p> +<em/WARNING:/ library destructors and functions registered with <tt/atexit()/ will not be called +so it is quite unsafe way to terminate your program. + +<sect2>Panic +<p> +<tt/void Panic (void)/ +<p> +This calls system's <tt/Panic/ handler - it shows a dialog box with the message +<tscreen><verb> +System error at:xxxx +</verb></tscreen> +where <tt/xxxx/ is last known execution address (caller). By default this is bound to the <tt/BRK/ +instruction, but it might be usable in debugging as kind of <tt/assert/. (Note that <tt/assert/ +is available as a separate function and will give you more information than that). +<p> +The system is halted after a call to <tt/Panic/ which means that library destructors will not be +called and some data may be lost (no wonder you're panicking). + +<sect2>CallRoutine +<p> +<tt/void CallRoutine (void *myFunct)/ +<p> +This is a system caller routine. You need to provide a pointer to a function and it will be immediately +called, unless the pointer is equal to <tt/NULL/. This is the main functionality of this function - +you don't need to check if the pointer is valid. + +<sect2>GetSerialNumber +<p> +<tt/unsigned GetSerialNumber (void)/ +<p> +This function returns the serial number of the system. It might be used for copy-protection. +However, please remember that Free Software is a true power and you are using it right now. + +<sect2>GetRandom +<p> +<tt/char GetRandom (void)/ +<p> +This function returns a random number. It can be also read from <tt/random/ e.g. +<tscreen><verb> +a=random; +</verb></tscreen> +but by calling this function you are sure that the results will be always different. +<tt/random/ is updated once a frame (50Hz PAL) and on every call to <tt/GetRandom/. +<p> +Note that this is not the same as the <tt/rand/ function from the standard library. <tt/GetRandom/ +will give you unpredictable results (if IRQs occur between calls to it) while +<tt/rand/ conforms to the standard and for a given seed (<tt/srand/) always returns with the +same sequence of values. + +<sect2>SetDevice +<p> +<tt/void SetDevice (char device)/ +<p> +This function sets the current device to the given. It might be used together with <tt/InitForIO/, +<tt/DoneWithIO/ and some Kernal routines. Unless the new device is a disk drive this only sets +new value in <tt/curDevice/, in the other case new disk driver is loaded from REU or internal RAM. + +<sect2>get_ostype +<p> +<tt/char get_ostype (void)/ +<p> +This function returns the GEOS Kernal version combined (by logical OR) with the machine type. Read +<tt/gsys.h/ for definitions of the returned values. + +<sect2>get_tv +<p> +<tt/char get_tv (void)/ +<p> +This function returns the PAL/NTSC flag combined (by logical OR) with the 40/80 columns flag. This is +not the best way to check if the screen has 40 or 80 columns since a PAL/NTSC check is always +performed and it can take as long as a full raster frame. If you just want to know if the +screen has 40 or 80 columns use the expression <tt/graphMode & 0x80/ which returns <tt/0/ for +40 columns and <tt/0x80/ for 80 columns. Remember that this value can be changed during +runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test +anything if not running under GEOS128. Use <tt/get_ostype/ to check it. Read <tt/gsys.h/ for +definitions of the returned values. + +<sect>Library Structures +<p> +To simplify usage and optimize passing parameters to functions I have declared several structures +which describe the most common objects. Some of these structures are bound to static addresses in +the GEOS data space (<tt/$8000-$8fff/), so you can use their fields directly in an optimized way. +Please see <tt/gsym.h/ to find them. All structures are defined in <tt/gstruct.h/ and you may +find also some comments there. + +<sect1>Graphics Structures + +<sect2>pixel +<p> +A simple structure describing a point on the screen. + +<sect2>fontdesc +<p> +This structure describes a font in one pointsize. There is the current font - <tt/struct fontdesc/ +bound to <tt/curFontDesc/. You can also force GEOS to use your own fonts by calling +<tt/LoadCharSet/. You just need to open a VLIR font file and load one record - one pointsize - +somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can +pass a pointer to the load address of that pointsize to <tt/LoadCharSet/. (Note that although +it has 'Load' in the name, that function loads only GEOS internal data structures, not data +from disk). + +<sect2>window +<p> +This widely used structure holds the description of a region of the screen. It describes the top-left and +bottom-right corners of a window. + +<sect2>iconpic +<p> +Maybe the name isn't the best - it has nothing with <tt/DoIcons/ but with bitmap functions - +<tt/BitmapUp/ for example. This structure holds the parameters needed to properly decode and show +a bitmap on the screen. The bitmap has to be encoded - if you have some non-GEOS bitmaps simply +convert them to Photo Scraps - this is the format used by all GEOS bitmap functions - <tt/DoIcons/ +too. + +<sect1>Icons +<p> +These structures describe click boxes (icons) that can be placed on screen or in a dialog box. + +<sect2>icondef +<p> +This is the definition of a single click box. Please see <tt/gstruct.h/ for a description of its fields. + +<sect2>icontab +<p> +This is the toplevel description of icons to be placed and enabled on the screen. This structure +has the following fields: +<itemize> + <item><tt/char number/ - total number of icons declared here + <item><tt/struct pixel mousepos/ - after finishing <tt/DoIcons/ the mouse pointer will be placed in + this point allowing you to have a hint for the user what the default action is + <item><tt/struct icondef tab[&rsqb/ - this table of size equal to <tt/icontab.number/ contains + descriptions for all icons +</itemize> + +<sect1>File and Disk + +<sect2>tr_se +<p> +This simple structure holds the track and sector number of something. Do not expect the track to be +in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K +expansion is utilized as RAMDisk with a layout of 4 tracks of 128 sectors each. However assuming that +a track number equal to 0 is illegal might be wise. + +<sect2>f_date +<p> +This is a placeholder for a file datestamp. This structure is also present in <tt/struct filehandle/. +GEOS is not Y2K compliant, so if the current file has in <tt/filehandle.date.year/ a value less than 86 +you can safely assume that it is e.g. 2004 and not 1904. + +<sect2>filehandle +<p> +This is the main file descriptor. It is either an entry in the directory (returned from file functions) +or its copy in <tt/dirEntryBuf/. This is optimized so you can safely get to the file's year e.g. +by testing <tt/dirEntryBuf.date.year/ - it will be compiled to simple <tt/LDA, STA/. + +<sect2>fileheader +<p> +This structure holds the fileheader description. You can load a file's header into the <tt/fileHeader/ +fixed area using <tt/GetFHdrInfo/. (note that <tt/fileHeader/ is a place in memory while +<tt/fileheader/ is a structure). +You will also need your own fileheader for <tt/SaveFile/. + +<sect1>System Structures + +<sect2>s_date +<p> +This structure is defined only for <tt/system_date/. It is slightly different from <tt/f_date/ +so I prepared this one. You can e.g. get or set the current time using <tt/system_date.s_hour/ and +<tt/system_date.s_minute/. Accesses to these will be optimized to simple <tt/LDA/ and <tt/STA/ +pair. + +<sect2>process +<p> +You should declare a table of that type to prepare data for <tt/InitProcesses/. The maximum number +of processes is 20, and the last entry has to be equal to <tt/{NULL,NULL}/, so this table may hold +only 21 entries. The first member of this structure (<tt/pointer/) holds the pointer to the called +function (void returning void), you will probably have to cast that pointer into <tt/unsigned int/. +The second field <tt/jiffies/ holds the amount of time between calls to that function. +On PAL systems there are 50 jiffies per second, while NTSC have 60 of them. + +<sect1>A few things in detail... +<p> +GEOSLib uses cc65 non-ANSI extensions to easily initialize data in memory. This is done with a +kind of array of unspecified length and unspecified type. Here is how it works: +<tscreen><verb> +void example = { + (char)3, (unsigned)3, (char)0 }; +</verb></tscreen> +Which will be compiled to following string of bytes: +<tscreen><verb> +_example: + .byte 3 + .word 3 + .byte 0 +</verb></tscreen> +As you see this way it is possible to define data of any type in any order. You must remember to +cast each member to proper type. + +<sect2>DoMenu structure +<p> +<tt/DoMenu/ is responsible for everything concerned with menu processing. Many, many GEOS programs +are just initializing the screen and menu and returning to <tt/MainLoop/. In GEOSLib it is the same as +returning from <tt/main/ function without using <tt/exit(0)/. +<p> +A menu is described by two types of data - menu descriptors and menu items. A descriptor contains +information about the following menu items, and items contain names of entries and either +pointers to functions to execute or, in case of nested menus, pointers to submenu descriptors. +Note that submenu descriptor can be top-level descriptor, there's no difference in structure, +just in the content. +<p> +Here is how a single descriptor looks like: +<tscreen><verb> +void myMenu = { + (char)top, (char)bottom, // this is the size of the menubox + (unsigned)left, (unsigned)right, // counting all items in the current descriptor + (char)number_of_items | type_of_menu, // number of following items ORed with + // type of this menu, it can be either + // HORIZONTAL or VERTICAL if you will have also bit 6 set then menu won't be closed + // after moving mouse pointer outside the menubox. You can have at most 31 items. +</verb></tscreen> +This is followed by <tt/number_of_items/ of following item description. +<tscreen><verb> + ... + "menuitemname", (char)item_type, (unsigned)pointer, + "nextitemname", (char)item_type, (unsigned)pointer, + ... + "lastitemname", (char)item_type, (unsigned)pointer }; + // Note that there isn't ending <tt/NULL/ or something like that. +</verb></tscreen> +<tt/pointer/ is a pointer to something, what it points for depends from <tt/item_type/. This one +can have following values: +<p> +<tt/MENU_ACTION/ - a function pointed by <tt/pointer/ will be called after clicking on the menu item +<p> +<tt/SUB_MENU/ - <tt/pointer/ points to next menu descriptor - a submenu +<p> +Both of them can be ORed with <tt/DYN_SUB_MENU/ and then the <tt/pointer/ points to a function +which will return in <tt/r0/ the needed pointer (to function to execute or a submenu). +<p> +For creating nested menus (you can have at most 8 levels of submenus) you need to declare such +a structure for each submenu and top level menu. + +<sect2>DoDlgBox command string +<p> +<tt/DoDlgBox/ is together with <tt/DoMenu/ one of the most powerful routines in GEOS. It is +responsible for creating dialog boxes, that is windows which task is to interact with the user. +The format of the command string is following: +<tscreen><verb> + (window size and position) + (commands and parameters) + NULL +</verb></tscreen> +There is a custom type defined for the command string: <tt/dlgBoxStr/. + +<sect3>Size and position +<p> +The first element can be specified in two ways - by using the default size and position or specifying +your own. The first case results in +<tscreen><verb> +const dlgBoxStr example = { + DB_DEFPOS (pattern_of_shadow), + ... // commands + DB_END }; +</verb></tscreen> +And the own size and position would be: +<tscreen><verb> +const dlgBoxStr example = { + DB_SETPOS (pattern, top, bottom, left, right) + ... // commands + DB_END }; +</verb></tscreen> + +<sect3>Commands +<p> +The next element of the <tt/DoDlgBox/ command string are the commands themselves. The first six commands are +default icons and the number of the selected icon will be returned from window processor. The icons are +<tt/OK, CANCEL, YES, NO, OPEN/, and <tt/DISK/. You can use predefined macros for using them, e.g.: +<tscreen><verb> + ... + DB_ICON(OK, DBI_X_0, DBI_Y_0), + ... +</verb></tscreen> +Note that the position is counted from top left corner of window, not entire screen and that the 'x' +position is counted in cards (8-pixel) and not in pixels. This is also true for all following commands. +<tt/DBI_X_0/ and <tt/DBI_Y_0/ are predefined (see <tt/gdlgbox.h/ for more), the default positions +which will cause icons to appear on a default window exactly where you would expect them. +<p> +<tt/DB_TXTSTR (x, y, text)/ will cause to show the given text in the window. +<p> +<tt/DB_VARSTR (x, y, ptr)/ works as above, but here you are passing a pointer to a zero page location +where the address of the text is stored. This is useful for information windows where only the text content +is variable. Consider following: +<tscreen><verb> +char text = "foo"; + ... + r15=(unsigned)text; // in code just before call to DoDlgBox + ... + DB_VARSTR (TXT_LN_X, TXT_LN_1_Y, &r15), + ... +</verb></tscreen> +will cause the word ``foo'' to appear in the window, but you may store the pointer to any text in +<tt/r15/ (in this case) before the call to DoDlgBox. +<p> +<tt/DB_GETSTR(x, y, ptr, length)/ - will add a input-from-keyboard feature. <tt/ptr/ works as in the +previous example and points to the location where the text is to be stored. Note that the contents of this +location will be shown upon creating the window. <tt/length/ is the maximum number of characters to input. +<p> +<tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to the given pointer. It is called on every keypress. +<p> +<tt/DB_GRPHSTR(ptr)/ - the data for this command is a pointer for <tt/GraphicsString/ commands. +<p> +<tt/DB_GETFILES(x, y)/ - for a standard window you should pass 4 for both x and y. This function +draws a file selection box and searches the current drive for files. Before the call to <tt/DoDlgBox/ you +must load <tt/r7L/ with the GEOS filetype of searched files and <tt/r10/ with the class text. In <tt/r5/ +you have to load a pointer to a <tt/char[17]/ where the selected filename will be copied. It works +like <tt/FindFTypes/ but is limited to first 16 files. +<p> +<tt/DB_OPVEC(ptr)/ - this sets a new pointer for the button press function, if you pass +<tt/RstrFrmDialogue/ here you will cause the window to close after pressing mouse button. +<p> +<tt/DB_USRICON(x, y, ptr)/ - places a single user icon (click box) on the window, <tt/ptr/ points at a +<tt/struct icondef/ but fields <tt/x/ and <tt/y/ are not used here. You can have at most 8 click +boxes in a window, this is an internal limit of the GEOS Kernal. +<p> +<tt/DB_USRROUT(ptr)/ - this command causes to immediately call the user routine pointed by <tt/ptr/. + +<sect2>GraphicsString command string +<p> +<tt/GraphicsString/ is a very powerful routine to initialize the whole screen at once. There are +predefined macros for all commands, names are self-explanatory, see them in <tt/ggraph.h/. The last +command has to be <tt/GSTR_END/. There is a custom type defined for the command string: <tt/graphicStr/. +<p> +Here is an example for clearing the screen: +<tscreen><verb> +const graphicStr example = { + MOVEPENTO(0,0), + NEWPATTERN(0), + RECTANGLETO(319,199) + GSTR_END }; +</verb></tscreen> + +<sect2>InitRam table +<p> +This type of data is used to initialize one or more bytes in different locations at once. The format is +the following: +<tscreen><verb> +void example = { + (unsigned)address_to_store_values_at, + (char)number_of_bytes_that_follow, + (char)data,(char)data (...) + // more such definitions + (unsigned)NULL // address of 0 ends the table + }; +</verb></tscreen> + +<sect2>Intercepting system vectors +<p> +It is possible to intercept events and hook into the GEOS Kernal using vectors. Here is a little example: +<tscreen><verb> +void_func oldVector; + +void NewVectorHandler(void) { + // do something and at the end call the old vector routine + oldVector(); +} + +void hook_into_system(void) { + oldVector = mouseVector; + mouseVector = NewVectorHandler; +} + +void remove_hook(void) { + mouseVector = oldVector; +} +</verb></tscreen> +<p> +In your <tt/main/ function you should call <tt/hook_into_system()/ but <em/after/ all calls to the GEOS +Kernal (like <tt/DoMenu/, <tt/DoIcons/, etc.) - right before passing control to the <tt/MainLoop()/. +Be warned that vectors are most likely to be changed by the GEOS Kernal also via other functions (like +<tt/GotoFirstMenu/, <tt/DoDlgBox/ and its derivatives etc.). It depends on what Kernal functions +you use and which vectors you altered. Unfortunately there is no exact list for GEOS 2.0, a complete +list for GEOS 1.x can be found in A. Boyce's Programmers' Reference Guide mentioned before. Most of the +information contained there should be still valid for GEOS 2.0. When calling a function that restores +the vector you should add a <tt/hook_into_system()/ call right after it. +<p> +It is critical to restore old vector values before exiting the program. If you have more than one +place where you call <tt/exit()/ then it might be worth to register <tt/remove_hook/ function to +be called upon exiting with <tt/atexit(&remove_hook);/ call. This way you will ensure that +such destructor will be always called. +<p> +That little example above intercepts <tt/mouseVector/. The <tt/NewVectorHandler/ function will be +called every time the mouse button changes status. Other important vectors you should know about +are: +<itemize> + <item><tt/appMain/ - this is called from within the <tt/MainLoop/ system loop + <item><tt/keyVector/ - called whenever a keypress occurs + <item><tt/intTopVector/ - called at the start of the IRQ routine + <item><tt/intBotVector/ - called at the end of the IRQ routine +</itemize> + +</article> diff --git a/doc/grc65.sgml b/doc/grc65.sgml new file mode 100644 index 000000000..583c6f80f --- /dev/null +++ b/doc/grc65.sgml @@ -0,0 +1,392 @@ +<!doctype linuxdoc system> +<article> + +<!-- Title information --> + +<title>grc65 -- GEOS Resource Compiler +<author><url name="Maciej 'YTM/Elysium' Witkowiak" url="mailto:ytm@elysium.pl"> +<and><url name="Greg King" url="mailto:gngking@erols.com"> +<date>VII 2000; VI,VII 2002; 2005-8-3 +<abstract> +This document describes a compiler that can create GEOS headers and menues for +cc65-compiled programs. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview +<p><bf/grc65/ is a part of cc65's GEOS support. The tool is necessary to +generate required and optional resources. A required resource for every GEOS +application is the header, that is: an icon, some strings, and some addresses. +Optional resources might be menu definitions, other headers (e.g., for data +files of an app.), dialog definitions, etc. Without an application's header, +GEOS is unable to load and start it. + +Currently, <bf/grc65/ supports only menues and the required header definition, +along with support for building applications with VLIR-structured overlays. + +<bf/grc65/ generates output in two formats: C header and <bf/ca65/ source (.s). +That is because the application header data must be in assembly format, while +the menu definitions can be translated easily into C. The purpose of the C +file is to include it as a header in only one project file. The assembly source +should be processed by <bf/ca65/ and linked to the application (read about +<ref name="the building process" id="building-seq">). + + + +<sect>Usage +<p>grc65 accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: grc65 [options] file +Short options: + -V Print the version number + -h Help (this text) + -o name Name the C output file + -s name Name the asm output file + -t sys Set the target system + +Long options: + --help Help (this text) + --target sys Set the target system + --version Print the version number +--------------------------------------------------------------------------- +</verb></tscreen> +Default output names are made from input names with extensions replaced by +<tt/.h/ and <tt/.s/. + + + +<sect>Resource file format +<p>A resource file has the name extension <tt/.grc/. That is not required, but +it will make for an easier recognition of the file's purpose. Also, <bf/cl65/ +recognizes those files. <bf/grc65/'s parser is very weak at the moment; so, +read the comments carefully, and write resources exactly as they are written +here. Look out for CAPS and small letters. Everything after a '<tt/;/' +until the end of the line is considered as a comment and ignored. See the +included <ref name="commented example .grc file" id="example-grc"> for a +better view of the situation. + + +<sect1>Menu definition +<p><tscreen><verb> +MENU menuName leftx,topy <ORIENTATION> { + "item name 1" <MENU_TYPE> pointer + ... + "item name x" <MENU_TYPE> pointer +}</verb></tscreen> +The definition starts with the keyword <tt/MENU/, then comes the menu's name, +which will be represented in C as <tt/const void/. Then are the co-ordinates +of the top left corner of the menu box. The position of the bottom right +corner is estimated, based on the length of item names and the menu's +orientation. It means that the menu box always will be as large as it should +be. Then, there's the orientation keyword; it can be either <tt/HORIZONTAL/ or +<tt/VERTICAL/. Between <tt/{/ and <tt/}/, there's the menu's +content. It consists of item definitions. First is an item name -- it has to +be in quotes. Next is a menu-type bit. It can be <tt/MENU_ACTION/ or +<tt/SUB_MENU/; either of them can be combined with the <tt/DYN_SUB_MENU/ bit +(see <url name="the GEOSLib documentation" url="geos.html"> for descriptions of +them). You can use C logical operators in expressions, but you have to do it +without spaces. So a dynamically created submenu will be something like: +<tscreen><verb> +"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic</verb></tscreen> +The last part of the item definition is a pointer which can be any name that is +present in the C source code that includes the generated header. It can point +to a function or to another menu definition. + +If you are doing sub(sub)menu definitions, remember to place the lowest level +definition first, and the top-level menu as the last one. That way the C +compiler won't complain about unknown names. + + +<sect1>Header definition +<p><tscreen><verb> +HEADER <GEOS_TYPE> "dosname" "classname" "version" { + author "Joe Schmoe" + info "This is my killer-app!" + date yy mm dd hh ss + dostype SEQ + mode any + structure SEQ + icon "sprite.raw" +}</verb></tscreen> +The header definition describes the GEOS header sector which is unique to +each file. The definition starts with the keyword <tt/HEADER/, then goes the +GEOS file-type. You can use only <tt/APPLICATION/ here at the moment. Then, +there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS +Class name (up to 12 characters), and the version info (up to 4 characters). +The version should be written as &dquot;<tt/V/x.y&dquot;, where <em/x/ is the +major, and <em/y/ is the minor, version number. Those fields, along with both +braces, are required. The lines between braces are optional, and will be replaced +by default and current values. The keyword <tt/author/ and its value in quotes name +the programmer, and can be up to 63 bytes long. <tt/info/ (in the same format) can +have up to 95 characters. If the <tt/date/ field is omitted, then the time of +that compilation will be placed into the header. Note that, if you do specify +the date, you have to write all 5 numbers. The <tt/dostype/ can be <tt/SEQ/, +<tt/PRG/, or <tt/USR/. <tt/USR/ is used by default; GEOS usually doesn't care. +The <tt/mode/ can be <tt/any/, <tt/40only/, <tt/80only/, or <tt/c64only/; and, +it describes system requirements. <tt/any/ will work on both 64-GEOS and +128-GEOS, in 40- and 80-column modes. <tt/40only/ will work on 128-GEOS in +40-column mode only. <tt/80only/ will work on only 128-GEOS in 80-column mode, +and <tt/c64only/ will work on only 64-GEOS. The default value for +<tt/structure/ is <tt/SEQ/ (sequential). You can put <tt/VLIR/ there, too; but +then, you also have to put in a third type of resource -- a memory definition. +The value of <tt/icon/ is a quoted file-name. The first 63 bytes of this file +are expected to represent a standard monochrome VIC sprite. The file gets accessed +when the generated assembly source is being processed by <bf/ca65/. Examples for +programs generating such files are <em/Sprite Painter/, <em/SpritePad/ and the +<url name="sp65 sprite and bitmap utility" url="sp65.html">. The default <tt/icon/ +is an empty frame internally represented in the generated assembly file. + + +<sect1>Memory definition +<p><tscreen><verb> +MEMORY { + stacksize 0x0800 + overlaysize 0x2000 + overlaynums 0 1 2 4 5 +}</verb></tscreen> +The memory definition is unique to each file and describes several attributes related +to the memory layout. It consists of the keyword <tt/MEMORY/ followed by braces which +contain optional lines. The value of <tt/stacksize/ can be either decimal (e.g. +<tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. <tt/0x1000/). The default value +of 0x400 comes from the linker configuration file. The value of <tt/backbuffer/ can be +either <tt/yes/ or <tt/no/. The further means that the application uses the system-supplied +background screen buffer while the latter means that the program uses the memory of the +background screen buffer for own purposes. The default value of <tt/yes/ comes from the +linker configuration file. If the <tt/structure/ in the header definition is set to the +value <tt/VLIR/ then it is possible and necessary to provide here the attributes of the +VLIR overlays. <tt/overlaysize/ defines the maximal size for all VLIR records but number +0. It can be either decimal (e.g. <tt/4096/) or hexadecimal with a <tt/0x/ prefix (e.g. +<tt/0x1000/). <tt/overlaynums/ defines the VLIR record numbers used by the application. +Skipped numbers denote empty records. In the example, record number 3 is missing. Read +<ref name="this description" id="building-vlir"> for details. + + + +<sect>Building a GEOS sequential application<label id="building-seq"> +<p>Before proceeding, please read the <url name="compiler" url="cc65.html">, +<url name="assembler" url="ca65.html">, and <url name="linker" url="ld65.html"> +documentation, and find the appropriate sections about building programs, in +general. + +GEOS support in cc65 is based on the <em/Convert v2.5/ format, well-known in +the GEOS world. It means that each file built with the cc65 package has to be +deconverted in GEOS, before it can be run. You can read a step-by-step +description of that in the <url name="GEOS section of the cc65 Compiler Intro" +url="intro-6.html#ss6.5">. + +Each project consists of four parts, two are provided by cc65. Those parts +are:<enum> +<item>application header +<item>start-up object +<item>application objects +<item>system library +</enum> +<bf/2./ and <bf/4./ come with cc65; however you have to write the application +yourself ;-) + +The application header is defined in the <tt/HEADER/ section of the <tt/.grc/ +file and is processed into an assembly <tt/.s/ file. You must assemble it, with +<bf/ca65/, into the object <tt/.o/ format. + +Assume that there are three input files: &dquot;<tt/test.c/&dquot; (a C +source), &dquot;<tt/test.h/&dquot; (a header file), and +&dquot;<tt/testres.grc/&dquot; (with menu and header definitions). Note the +fact that I <em/don't recommend/ naming that file &dquot;<tt/test.grc/&dquot; +because you will have to be very careful with names (<bf/grc65/ will make +&dquot;<tt/test.s/&dquot; and &dquot;<tt/test.h/&dquot; out of +&dquot;<tt/test.grc/&dquot; by default; and you don't want that because +&dquot;<tt/test.s/&dquot; is compiled from &dquot;<tt/test.c/&dquot;, and +&dquot;<tt/test.h/&dquot; is something completely different)! + +<bf/One important thing/ -- the top of &dquot;<tt/test.c/&dquot; looks like: +<tscreen><verb> +#include <geos.h> +#include "testres.h" +</verb></tscreen> +There are no other includes. + + +<sect1>Building the GEOS application using cl65 +<p>This is a simple one step process: +<tscreen><verb> +cl65 -t geos-cbm -O -o test.cvt testres.grc test.c +</verb></tscreen> +Always place the <tt/.grc/ file as first input file on the command-line in order +to make sure that the generated <tt/.h/ file is available when it is needed for +inclusion by a <tt/.c/ file. + + +<sect1>Building the GEOS application without cl65 +<sect2>First step -- compiling the resources +<p> +<tscreen><verb> +grc65 -t geos-cbm testres.grc +</verb></tscreen> +will produce two output files: &dquot;<tt/testres.h/&dquot; and +&dquot;<tt/testres.s/&dquot;. + +Note that &dquot;<tt/testres.h/&dquot; is included at the top of +&dquot;<tt/test.c/&dquot;. So, resource compiling <em/must be/ the first step. + +<sect2>Second step -- assembling the application header +<p> +<tscreen><verb> +ca65 -t geos-cbm testres.s +</verb></tscreen> +And, voilá -- &dquot;<tt/testres.o/&dquot; is ready. + +<sect2>Third step -- compiling the code +<p> +<tscreen><verb> +cc65 -t geos-cbm -O test.c +ca65 -t geos-cbm test.s +</verb></tscreen> +That way, you have a &dquot;<tt/test.o/&dquot; object file which +contains all of the executable code. + +<sect2>Fourth and last step -- linking the application +<p> +<tscreen><verb> +ld65 -t geos-cbm -o test.cvt testres.o test.o geos-cbm.lib +</verb></tscreen> +The last file is the GEOS system library. + +The resulting file &dquot;<tt/test.cvt/&dquot; is an executable that's +contained in the well-known GEOS <em/Convert/ format. Note that its name +(<tt/test.cvt/) isn't important; the real name, after deconverting, is the DOS name +that was given in the header definition. + +At each step, a <tt/-t geos-cbm/ was present on the command-line. That switch is +required for the correct process of GEOS sequential application building. + + + +<sect>Building a GEOS VLIR overlay application<label id="building-vlir"> +<p>Large GEOS applications typically don't fit in one piece in their designated +memory area. They are therefore split into overlays which are loaded into memory +on demand. The individual overlays are stored as records of a VLIR (Variable +Length Index Record) file. When GEOS starts a VLIR overlay appliation it loads +record number 0 which is supposed to contain the main program. The record numbers +starting with 1 are to be used for the actual overlays. + +In "<tt>cc65/samples/geos</tt>" there's a VLIR overlay demo application consisting +of the files "<tt/overlay-demo.c/" and "<tt/overlay-demores.grc/". + + +<sect1>Building the GEOS overlay application using cl65 +<p>This is a simple one step process: +<tscreen><verb> +cl65 -t geos-cbm -O -o overlay-demo.cvt -m overlay-demo.map overlay-demores.grc overlay-demo.c +</verb></tscreen> +Always place the <tt/.grc/ file as first input file on the command-line in order +to make sure that the generated <tt/.h/ file is available when it is needed for +inclusion by a <tt/.c/ file. + +You will almost certainly want to generate a map file that shows (beside a lot of +other infos) how large your individual overlays are. This info is necessary to tune +the distribution of code into the overlays and to optimize the memory area reserved +for the overlays. + + +<sect1>Building the GEOS overlay application without cl65 +<sect2>First step -- compiling the overlay resources +<p> +<tscreen><verb> +grc65 -t geos-cbm overlay-demores.grc +</verb></tscreen> + +<sect2>Second step -- assembling the overlay application header +<p> +<tscreen><verb> +ca65 -t geos-cbm overlay-demores.s +</verb></tscreen> + +<sect2>Third step -- compiling the overlay code +<p> +<tscreen><verb> +cc65 -t geos-cbm -O overlay-demo.c +ca65 -t geos-cbm overlay-demo.s +</verb></tscreen> + +<sect2>Fourth and last step -- linking the overlay application +<p> +<tscreen><verb> +ld65 -t geos-cbm -o overlay-demo.cvt -m overlay-demo.map overlay-demores.o overlay-demo.o geos-cbm.lib +</verb></tscreen> + + + +<sect>Bugs and feedback +<p>This is the first release of <bf/grc65/, and it contains bugs, for sure! I +am aware of them; I know that the parser is weak, and if you don't follow the +grammar rules strictly, then everything will crash. However, if you find an +interesting bug, mail me. :-) Mail me also for help with writing your +<tt/.grc/ file correctly if you have problems with it. I would appreciate +comments also, and help on this file because I am sure that it can be written +better. + + + +<sect>Legal stuff +<p><bf/grc65/ is covered by the same license as the whole cc65 package, so you +should see its documentation for more info. Anyway, if you like it, and want +to encourage me to work more on it, send me a postcard with a sight of your +neighbourhood, city, region, etc. Or, just e-mail me with info that you +actually used it. See <url name="the GEOSLib documentation" url="geos.html"> +for addresses. + + + +<appendix> +<sect>Appendix A -- example.grc<label id="example-grc"> +<p><tscreen><verb> +; Note that MENU can define both menues and submenues. +; If you want to use any C operators (such as "|", "&", etc.), do it WITHOUT +; any spaces between the arguments (the parser is simple and weak). + +MENU subMenu1 15,0 VERTICAL +; This is a vertical menu, placed at (15,0). +{ +; There are three items, all of them will call functions. +; The first and third ones are normal functions, see GEOSLib documentation for +; information about what the second function should return (it's a dynamic one). + "subitem1" MENU_ACTION smenu1 + "subitem2" MENU_ACTION|DYN_SUB_MENU smenu2 + "subitem3" MENU_ACTION smenu3 +} + +;; Format: MENU "name" left,top ALIGN { "itemname" TYPE pointer ... } + +MENU mainMenu 0,0 HORIZONTAL +; Here, we have our main menu, placed at (0,0), and it is a horizontal menu. +; Because it is a top-level menu, you would register it in your C source by +; using: DoMenu(&ero;mainMenu); +{ +; There are two items -- a submenu and an action. +; This calls a submenu named subMenu1 (see previous definition). + "first sub-menu" SUB_MENU subMenu1 +; This will work the same as an EnterDeskTop() call in C source code. + "quit" MENU_ACTION EnterDeskTop +} + +;; Format: HEADER <GEOS_TYPE> "dosname" "classname" "version" + +HEADER APPLICATION "MyFirstApp" "Class Name" "V1.0" +; This is a header for an APPLICATION which will be seen in the directory as a +; file named MyFirstApp with the Class-string "Class Name V1.0" +{ +; Not all fields are required, default and current values will be used. + author "Maciej Witkowiak" ; always in quotes! + info "Information text" ; always in quotes! +; date yy mm dd hh ss ; always 5 fields! +; dostype seq ; can be: PRG, SEQ, USR (only all UPPER- or lower-case) +; structure seq ; can be: SEQ, VLIR (only UPPER- or lower-case) + mode c64only ; can be: any, 40only, 80only, c64only +}</verb></tscreen> +</article> diff --git a/doc/index.sgml b/doc/index.sgml new file mode 100644 index 000000000..e0b110ead --- /dev/null +++ b/doc/index.sgml @@ -0,0 +1,179 @@ +<!doctype linuxdoc system> + +<article> +<title>cc65 Documentation Overview +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2005-8-6 + +<abstract> +Main documentation page, contains links to other available stuff. +</abstract> + +<sect>Program documentation<p> + +<descrip> + + <tag><htmlurl url="ar65.html" name="ar65.html"></tag> + Describes the ar65 archiver. + + <tag><htmlurl url="ca65.html" name="ca65.html"></tag> + Describes the ca65 macro assembler. + + <tag><htmlurl url="ca65html.html" name="ca65html.html"></tag> + Describes the ca65html assembler-source-to-HTML converter. + + <tag><htmlurl url="cc65.html" name="cc65.html"></tag> + Describes the cc65 C compiler. + + <tag><htmlurl url="cl65.html" name="cl65.html"></tag> + Describes the cl65 compile & link utility. + + <tag><htmlurl url="co65.html" name="co65.html"></tag> + Describes the co65 object-file converter. + + <tag><htmlurl url="da65.html" name="da65.html"></tag> + Describes the da65 6502/65C02 disassembler. + + <tag><htmlurl url="grc65.html" name="grc65.html"></tag> + Describes the GEOS resource compiler (grc65). + + <tag><htmlurl url="ld65.html" name="ld65.html"></tag> + Describes the ld65 linker. + + <tag><htmlurl url="od65.html" name="od65.html"></tag> + Describes the od65 object-file analyzer. + + <tag><htmlurl url="sp65.html" name="sp65.html"></tag> + Describes the sprite and bitmap utility. + +</descrip> + + +<sect>Usage<p> + +<descrip> + + <tag><htmlurl url="intro.html" name="intro.html"></tag> + Describes the use of the tools, by building a short &dquot;hello world&dquot; + example. + + <tag><htmlurl url="coding.html" name="coding.html"></tag> + Contains hints on creating the most effective code with cc65. + + <tag><htmlurl url="compile.txt" name="compile.txt"></tag> + How to compile cc65 and the support tools. + + <tag><htmlurl url="using-make.html" name="using-make.html"></tag> + Build programs, using the GNU Make utility. + + <tag><htmlurl url="customizing.html" name="customizing.html"></tag> + How to use the cc65 toolset for a custom hardware platform (a target system + not currently supported by the cc65 library set). + + <tag><htmlurl url="debugging.html" name="debugging.html"></tag> + Debug programs, using the VICE emulator. + +</descrip> + + +<sect>Library information and other references<p> + +<descrip> + + <tag><htmlurl url="funcref.html" name="funcref.html"></tag> + A (currently incomplete) function reference. + + <tag><htmlurl url="dio.html" name="dio.html"></tag> + Low-level disk I/O API. + + <tag><htmlurl url="geos.html" name="geos.html"></tag> + The GEOSLib manual. + + <tag><htmlurl url="internal.txt" name="internal.txt"></tag> + A somewhat older text describing several cc65 internals. + + <tag><htmlurl url="library.html" name="library.html"></tag> + An overview over the cc65 runtime and C libraries. + + <tag><htmlurl url="smc.html" name="smc.html"></tag> + Describes Christian Krügers macro package for writing self modifying + assembler code. + + <tag><url name="6502 Binary Relocation Format document" + url="http://www.6502.org/users/andre/o65/fileformat.html"></tag> + Describes the o65 file format that is used for dynamically loadable modules + and LUnix programs. + +</descrip> + + +<sect>Platform-specific information<p> + +<descrip> + + <tag><htmlurl url="apple2.html" name="apple2.html"></tag> + Topics specific to the Apple ][. + + <tag><htmlurl url="apple2enh.html" name="apple2enh.html"></tag> + Topics specific to the enhanced Apple //e. + + <tag><htmlurl url="atari.html" name="atari.html"></tag> + Topics specific to the Atari 8-bit machines. + + <tag><htmlurl url="atmos.html" name="atmos.html"></tag> + Topics specific to the Oric Atmos. + + <tag><htmlurl url="c128.html" name="c128.html"></tag> + Topics specific to the Commodore 128. + + <tag><htmlurl url="c16.html" name="c16.html"></tag> + Topics specific to the Commodore 16/116. + + <tag><htmlurl url="c64.html" name="c64.html"></tag> + Topics specific to the Commodore 64. + + <tag><htmlurl url="cbm510.html" name="cbm510.html"></tag> + Topics specific to the Commodore 510. + + <tag><htmlurl url="cbm610.html" name="cbm610.html"></tag> + Topics specific to the Commodore 610. + + <tag><htmlurl url="lynx.html" name="lynx.html"></tag> + Topics specific to the Atari Lynx Game Console. + + <tag><htmlurl url="nes.html" name="nes.html"></tag> + Topics specific to the Nintendo Entertainment System. + + <tag><htmlurl url="pet.html" name="pet.html"></tag> + Topics specific to the Commodore PET machines. + + <tag><htmlurl url="plus4.html" name="plus4.html"></tag> + Topics specific to the Commodore Plus/4. + + <tag><htmlurl url="supervision.html" name="supervision.html"></tag> + Topics specific to the Supervision Console. + + <tag><htmlurl url="vic20.html" name="vic20.html"></tag> + Topics specific to the Commodore VIC20. + +</descrip> + + +<sect>Miscellaneous<p> + +<descrip> + + <tag><htmlurl url="newvers.txt" name="newvers.txt"></tag> + Somewhat outdated. Lists the differences between my cc65 releases + and the original Atari version that was created by J. R. Dunning. + + <tag><htmlurl url="BUGS" name="BUGS"></tag> + Known cc65 bugs. + + <tag><htmlurl url="CREDITS" name="CREDITS"></tag> + Here is who helped with the compiler and other tools. + +</descrip> + +</article> + diff --git a/doc/internal.txt b/doc/internal.txt new file mode 100644 index 000000000..0dca618ea --- /dev/null +++ b/doc/internal.txt @@ -0,0 +1,207 @@ + + + Internals doc for CC65 + + + +Stacks: +------- + +The program stack used by programs compiled with CC65 is located in high +memory. The stack starts there and grows down. Arguments to functions, local +data etc are allocated on this stack, and deallocated when functions exit. + +The program code and data is located in low memory. The heap is located +between the program code and the stack. The default size for the parameter +stack is 2K, you may change this for most platforms in the linker +configuration. + +Note: The size of the stack is only needed if you use the heap, or if you +call the stack checking routine (_stkcheck) from somewhere in your program. + +When calling other functions, the return address goes on the normal 6502 +stack, *not* on the parameter stack. + + + +Registers: +---------- + +Since CC65 is a member of the Small-C family of compilers, it uses the notion +of a 'primary register'. In the CC65 implementation, I used the AX register +pair as the primary register. Just about everything interesting that the +library code does is done by somehow getting a value into AX, and then calling +some routine or other. In places where Small-C would use a secondary +register, top-of-stack is used, so for instance two argument function like +integer-multiply work by loading AX, pushing it on the stack, loading the +second value, and calling the internal function. The stack is popped, and the +result comes back in AX. + + + +Calling sequences: +------------------ + +C functions are called by pushing their args on the stack, and JSR'ing to the +entry point. (See ex 1, below) If the function returns a value, it comes back +in AX. NOTE!!! A potentially significant difference between the CC65 +environment and other C environments is that the CALLEE pops arguments, not +the CALLER. (This is done so as to generate more compact code) In normal use, +this doesn't cause any problems, as the normal function entry/exit conventions +take care of popping the right number of things off the stack, but you may +have to worry about it when doing things like writing hand-coded assembly +language routines that take variable numbers of arguments. More about that +later. + +Ex 1: Function call: Assuming 'i' declared int and 'c' declared + char, the following C code + + i = baz(i, c); + + in absence of a prototype generates this assembler code. I've added + the comments. + + lda _i ; get 'i', low byte + ldx _i+1 ; get 'i', hi byte + jsr pushax ; push it + lda _c ; get 'c' + ldx #0 ; fill hi byte with 0 + jsr pushax ; push it + ldy #4 ; arg size + jsr _baz ; call the function + sta _i ; store the result + stx _i+1 + + In presence of a prototype, the picture changes slightly, since the + compiler is able to do some optimizations: + + lda _i ; get 'i', low byte + ldx _i+1 ; get 'i', hi byte + jsr pushax ; push it + lda _c ; get 'c' + jsr pusha ; push it + jsr _baz ; call the function + sta _i ; store the result + stx _i+1 + + +Note that the two words of arguments to baz were popped before it exitted. +The way baz could tell how much to pop was by the argument count in Y at call +time. Thus, even if baz had been called with 3 args instead of the 2 it was +expecting, that would not cause stack corruption. + +There's another tricky part about all this, though. Note that the args to baz +are pushed in FORWARD order, ie the order they appear in the C statement. +That means that if you call a function with a different number of args than it +was expecting, they wont end up in the right places, ie if you call baz, as +above, with 3 args, it'll operate on the LAST two, not the first two. + + + +Symbols: +-------- + +CC65 does the usual trick of prepending an underbar ('_') to symbol names when +compiling them into assembler. Therefore if you have a C function named +'bar', CC65 will define and refer to it as '_bar'. + + + +Systems: +-------- + +Supported systems at this time are: C64, C128, Plus/4, CBM 500, CBM 600/700, +the newer PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to +Kevin Ruland, who did the port). + +C16: Works with unexpanded or memory expanded C16 and C116 machines. + However, a maximum of 32KB from the total memory is used. The Plus/4 + target supports up to 64K of memory, but has a small code overhead + because of the banking routines involved. Apart from this additional + overhead, the Plus/4 target and the C16 target are the same. 16K + machines (unexpanded C16) have 12K of memory for C programs available, + machines with 32K or more have 28K available. The actual amount of + memory is auto detected. + +C64: The program runs in a memory configuration, where only the kernal ROM + is enabled. The text screen is expected at the usual place ($400), so + 50K of memory are available to the program. + +C128: The startup code will reprogram the MMU, so that only the kernal ROM + is enabled. This means, there are 41K of memory available to the + program. + +Plus/4: Works with bank switching so 59K of memory are available to the + program. + +CBM 500: + The C program runs in bank #0 and has a total of 48K memory available. + This is less than what is available on its bigger brothers (CBM + 600/700) because the character data and video RAM is placed in the + execution bank (#0) to allow the use of sprites. + +CBM 600/700: + The C program runs in a separate segment and has almost full 64K of + memory available. + +PET: The startup code will adjust the upper memory limit to the installed + memory. However, only linear memory is used, this limits the top to + $8000, so on a 8032 or similar machine, 31K of memory are available to + the program. + +Apple ][: + The program starts at $803, end of RAM is $95FF, so 35.5K of memory + (including stack) are available to the program. + +Atari: The startup code will adjust the upper memory limit to the installed + memory detected at runtime. The programmer can adjust the upper memory + limit by setting the __RESERVED_MEMORY__ variable at link time. The + given __RESERVED_MEMORY__ value will be subtracted from the upper + memory limit used by the runtine. This memory could be used as graphics + memory, for example. + In the default case (no setting of __RESERVED_MEMORY__) the upper + memory limit is $9C1F (with Basic cartridge) and $BC1F (without + cartridge). The program starts at $2E00 by default. + These values are for a 48K or 64K machine. + +Note: The above numbers do not mean that the remaining memory is unusable. +However, it is not linear memory and must be accessed by other, nonportable +methods. I'm thinking about a library extension that allows access to the +additional memory as a far heap, but these routines do not exist until now. + + + +Inline Assembly: +---------------- + +CC65 allows inline assembly by a special keyword named "asm". Inline assembly +looks like a function call. The string in parenthesis is output in the +assembler file. + +Example, insert a break instruction into the code: + + asm ("brk") + +Beware: Be careful when inserting inline code since this may collide with +the work of the optimizer. + + + +Pseudo variables: +----------------- + +There are two special variables available named __AX__ and __EAX__. These +variables must never be declared (this gives an error), but may be used as any +other variable. However, accessing these variables will access the primary +register that is used by the compiler to evaluate expressions, return +functions results and pass parameters. + +This feature is useful with inline assembly and macros. For example, a macro +that reads a CRTC register may be written like this: + +#define wr(idx) (__AX__=(idx), \ + asm ("sta $2000"), \ + asm ("lda $2000"), \ + asm ("ldx #$00"), \ + __AX__) + diff --git a/doc/intro.sgml b/doc/intro.sgml new file mode 100644 index 000000000..c5ef7956a --- /dev/null +++ b/doc/intro.sgml @@ -0,0 +1,527 @@ +<!doctype linuxdoc system> + +<article> + +<title>cc65 Compiler Intro +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">, +<and>CbmNut, <htmlurl url="mailto:cbmnut@hushmail.com" name="cbmnut@hushmail.com">, +<and><url name="Greg King" url="mailto:gngking@erols.com"> +<date>2005-7-22 + +<abstract> +How to use the cc65 C language system -- an introduction. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This is a short intro of how to use the compiler and the bin-utils. It contains +a step-by-step example of how to build a complete application from one C and +one assembly modules. This file does <em/not/ contain a complete reference for +the tools used in the process. There are separate files describing those tools, +in detail (see <url url="index.html">). + +I do assume that you have downloaded and installed the compiler and +target-specific files. Windows users should use the friendly .exe installer +(named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the +version number if necessary). It does not only install the target files, but +will also set up necessary environment variables for you. + +If you're going for the .ZIP archives, please note that there is one file for +the host platform (Windows, DOS or OS/2), one file for each target platform +(C64 or whatever) and a separate file containing the docs (which include the +file you're currently reading). So for most uses, you will need at least 3 +files and unpack all three into one directory. In case of the .ZIP archives, +you will also need to set the environment variables <tt/CC65_INC/, +<tt/LD65_LIB/ and <tt/LD65_CFG/ as described below. + +<bf/Note/: There is a much simpler way to compile this example, by using the +<bf/cl65/ compile-and-link utility. However, it makes sense to understand how +the separate steps work. How to do the example with the <bf/cl65/ utility is +described <ref id="using-cl65" name="later">. + + +<sect1>Before we start<p> + +You will find a copy of the sample modules, used in the next section, in the +"<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with +missing include files and/or libraries, please check the environment variables +<tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the +<tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you +installed cc65. + + +<sect1>The sample modules<p> + +To explain the development flow, I will use the following example modules: + +hello.c: +<tscreen><code> + #include <stdio.h> + #include <stdlib.h> + + extern const char text[]; /* In text.s */ + + int main (void) + { + printf ("%s\n", text); + return EXIT_SUCCESS; + } +</code></tscreen> + +text.s: +<tscreen><code> + .export _text + _text: .asciiz "Hello world!" +</code></tscreen> + + +<sect1>Translation phases<p> + +We assume that the target file should be named "hello", and the target system +is the C64. + +<tscreen><verb> + +---------+ + | hello.c | + +---------+ + | + cc65 + \/ + +---------+ +---------+ +---------+ + | hello.s | | text.s | | crt0.o | + +---------+ +---------+ +---------+ + | | | + ca65 ca65 ar65 + \/ \/ \/ + +---------+ +---------+ +---------+ + | hello.o | | text.o | | c64.lib | + +---------+ +---------+ +---------+ + | \ / + | \ / + | \ / + +----------------------->ld65< + \/ + hello +</verb></tscreen> + +<tt/crt0.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime +and C library) are provided in binary form in the cc65 package. Actually, the +startup code is contained in the library, so you won't need to care about it. + + + +<sect>The compiler<p> + +The compiler translates one C source into one assembly source, for each +invocation. It does <em/not/ create object files directly, and it is <em/not/ +able to translate more than one file per run. + +In the example above, we would use the following command line, to translate +<tt/hello.c/ into <tt/hello.s/: + +<tscreen><verb> + cc65 -O -t c64 hello.c +</verb></tscreen> + +The <tt/-O/ switch tells the compiler to do an additional optimizer run, which +is usually a good idea, since it makes the code smaller. If you don't care +about the size, but want to have slightly faster code, use <tt/-Oi/ to inline +some runtime functions. + +The <tt/-t/ switch is followed by the target system name. + +If the compiler does not complain about errors in our "hello world" program, we +will have a file named "<tt/hello.s/", in our directory, that contains the +assembly source for the <bf/hello/ module. + +For more information about the compiler, see <url url="cc65.html">. + + + +<sect>The assembler<p> + +The assembler translates one assembly source into an object file, for each +invocation. The assembler is <em/not/ able to translate more than one source +file per run. + +Let's translate the "hello.s" and "text.s" files from our example: + +<tscreen><verb> + ca65 hello.s + ca65 -t c64 text.s +</verb></tscreen> + +The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the +text is converted from the input character-set (usually ISO-8859-1) into the +target character-set (PETSCII, in this example) by the assembler. The +compiler-generated file <tt/hello.s/ does not contain any character constants, +so specification of a target is not necessary (it wouldn't do any harm, +however). + +If the assembler does not complain, we should now have two object files (named +<tt/hello.o/ and <tt/text.o/) in the current directory. + +For more information about the assembler, see <url url="ca65.html">. + + + +<sect>The linker<p> + +The linker combines several object and library files into one output file. +<bf/ld65/ is very configurable, but fortunately has built-in configurations, +so we don't need to mess with configuration files, here. + +The compiler uses small functions to do things that cannot be done inline +without a big impact on code size. Those runtime functions, together with the +C library, are in an object-file archive named after the system, in this case, +"<tt/c64.lib/". We have to specify that file on the command line, so that the +linker can resolve those functions. + +Let's link our files to get the final executable: + +<tscreen><verb> + ld65 -o hello -t c64 hello.o text.o c64.lib +</verb></tscreen> + +The argument after <tt/-o/ specifies the name of the output file, the argument +after <tt/-t/ gives the target system. The following arguments are object +files or libraries. Since the target library resolves imports in <tt/hello.o/ +and <tt/text.o/, it must be specified <em/after/ those files. + +After a successful linker run, we have a file named "<tt/hello/", ready for +our C64! + +For more information about the linker, see <url url="ld65.html">. + + + +<sect>The easy way (using the cl65 utility)<label id="using-cl65"><p> + +The <bf/cl65/ utility is able to do all of the steps described above, in just +one command line, and it has defaults for some options that are very +well-suited for our example. + +To compile both files into one executable, enter: + +<tscreen><verb> + cl65 -O hello.c text.s +</verb></tscreen> + +The <bf/cl65/ utility knows how to translate C files into object files (it will +call the compiler, and then the assembler). It does know also how to create +object files from assembly files (it will call only the assembler, for that). +It knows how to build an executable (it will pass all object files to the +linker). And finally, it has the C64 as a default target, and will supply the +correct startup file and runtime library names to the linker, so you don't +have to care about that. + +The one-liner above should give you a C64 executable named "<tt/hello/" in the +current directory. + +For more information about the compile & link utility, see <url +url="cl65.html">. + + + +<sect>Running The Executable<p> + +<em/Note: this section is incomplete!/ + +Depending on the target, cc65 chooses several methods of making a program +available for execution. Here, we list sample emulators and instructions for +running the program. Unless noted, similar instructions would also apply to a +real machine. One word of advice: we suggest you clear the screen at the +start, and wait for a keypress at the end of your program, as each target +varies in its start and exit conditions. + + +<sect1>Apple + +<sect2>AppleWin<p> +Available at <url +url="http://applewin.berlios.de/">: + +Emulates Apple ][/enhanced Apple //e computers, with +sound, video, joysticks, serial port, and disk images. Includes monitor. Only +for Windows. The package comes with a DOS 3.3 disk (called "master.dsk") image; +however, you will need <bf/AppleCommander 1.3.5/ or later (available at <url +url="http://applecommander.sourceforge.net/">). + +Compile the tutorial with + +<tscreen><verb> +cl65 -O -t apple2 hello.c text.s +</verb></tscreen> +for the Apple ][, or: +<tscreen><verb> +cl65 -O -t apple2enh hello.c text.s +</verb></tscreen> +for the enhanced Apple //e. + +Then, put the file onto an Apple disk image, for use with an emulator. Copy +the <tt/master.dsk/ which comes with <bf/AppleWin/, and rename it to +<tt/cc65.dsk/, then use <bf/AppleCommander/: + +<tscreen><verb> +java -jar ac.jar -cc65 cc65.dsk test B < hello +</verb></tscreen> + +Note that a convention in the Apple world is that "hello" is the file which is +run automatically upon booting a DOS disk, sort of like the "autoexec.bat" of +the MSDOS/Windows world. We've avoided that in the example, however. Also, +the <tt/B/ parameter must be in caps., and "test" is the name of the program as +it will appear on the Apple disk. + +Start the emulator, click on the <bf/Disk 1/ icon, and point to <bf/cc65.dsk/; +then, click the big Apple logo, to boot the system. Then, type this on the +Apple: + +<tscreen><verb> +BRUN TEST +</verb></tscreen> + +You will see the "Hello, World!" appear on the same line. Thanks to Oliver +Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> for his help +in completing this section. + + +<sect1>Atari + +<sect2>Atari800Win PLus<p> +Available at <url +url="http://www.atari.org.pl/PLus/index_us.htm">: + +Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk +images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM +expansions. Includes monitor. Unfortunately, only for Windows. You will need +the emulator, "atarixl.rom" or "atariosb.rom"/"ataribas.rom", and "dos25.xfd" +files (not supplied). + +Compile the tutorial with + +<tscreen><verb> +cl65 -O -t atari hello.c text.s +</verb></tscreen> + +Start the emulator, choose <bf/File>Autoboot image/ or <bf/File>Load +executable/, and point to the "<bf/hello/" executable. It is customary to +rename executables of that type to "<bf/hello.xex/". The file has a 7-byte +header meant to be loaded directly from Atari DOS 2/2.5 or compatibles. + +On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible. +Turn on the computer, type + +<tscreen><verb> +DOS +</verb></tscreen> + +at the BASIC prompt, then choose <bf/N. CREATE MEM.SAV/, +then choose <bf/L. BINARY LOAD/, and enter <tt/HELLO/. + +The emulation, also, supports that method. Look at <bf/Atari>Settings/, and +check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari>Hard +disks/, and set the path of <bf/H1:/ to your executables directory, then use +"<bf/H0:HELLO.XEX/" in the above procedure (after pressing <tt/L/), to access +your harddrive directly. + +<bf/Note/: There is no delay after the program exits, as you are returned +to the DOS menu. Your C program should wait for a keypress if you want to see +any output. + + +<sect1>Atmos + +<sect2>Oricutron<p> +Available at <url +url="http://code.google.com/p/oriculator/">: + +Emulates Oric-1 and Atmos computers, with sound, disk images, +scanline-exact NTSC/PAL video, and movie export. Includes monitor. +Fortunately for all SDL platforms. You will just need the emulator, all +ROMs are supplied. + +Compile the tutorial with + +<tscreen><verb> +cl65 -O -t atmos hello.c text.s -o hello.tap +</verb></tscreen> + +Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to +the "<bf/hello.tap/" executable. The file has an auto start header meant to +be loaded directly from tape. + +On a real Atmos, you would need a tape drive. +Turn on the computer, type + +<tscreen><verb> +CLOAD"" +</verb></tscreen> + +at the BASIC prompt. + +The emulation, also, supports that method. + + +<sect1>Commodore + +<sect2>VICE<p> +Available at <url +url="http://www.viceteam.org/">: + +Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports +printers, serial port and adapters, stereo sound, disk drives and images, RAM +expansions, cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, +and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2, +BeOS x86, Acorn RISC OS, and most Unixes. + +Compile the tutorial with +<tscreen><verb> +cl65 -O -t <sys> hello.c text.s +</verb></tscreen> +Substitute the name of a Commodore computer for that <tt/<sys>/: +<itemize> +<item><tt/c128/ +<item><tt/c16/ +<item><tt/c64/ +<item><tt/cbm510/ +<item><tt/cbm610/ +<item><tt/pet/ +<item><tt/plus4/ +<item><tt/vic20/ +</itemize> + +Start the desired version of the emulator (CBM510 and CBM610 programs run on +the CBM II [<tt/xcbm2/] emulator). + +In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape +image...</bf>, choose your executable, and click <bf/OK/. + +In the Unix versions, hold down the mouse's first button. Move the pointer to +<bf>Smart-attach disk/tape...</bf>, and release the button. Choose your +executable, and click <bf/Autostart/. + +The file has a 14-byte header which corresponds to a PRG-format BASIC program, +consisting of a single line, similar to this: + +<tscreen><code> +1000 sys2061 +</code></tscreen> + +On a real Commodore with attached disk drive, you would type: + +<tscreen><verb> +LOAD "0:HELLO",8 +</verb></tscreen> + +for VIC-20/C64, or: + +<tscreen><verb> +DLOAD "HELLO" +</verb></tscreen> + +on PET/CBM II/C128/C16/Plus 4; then, type + +<tscreen><verb> +RUN +</verb></tscreen> + +On a Commodore 128, you can combine those two commands: +<tscreen><verb> +RUN "HELLO" +</verb></tscreen> + +The output will appear on a separate line, and you will be returned to a BASIC +prompt. + + +<sect1>GEOS<p> +Available at <it/Click Here Software's/ <url +url="http://cbmfiles.com/geos/index.html" name="GEOS download section">: + +<it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it> +It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User +Interface) for Commodore's computer models <bf/64/ and <bf/128/. It can be +controlled by many different types of input devices: +<itemize> +<item>keyboard +<item>joysticks +<item>mice +<item>trackballs +<item>graphics drawing tablets +<item>light-pens +</itemize> + +The tutorial files are different for GEOS. You will find them "next door," in +"<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and +"<tt/hello1res.grc/". + +Compile the tutorial with +<tscreen><verb> +cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c +</verb></tscreen> +Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk. + +Boot the GEOS master disk/image. + +<quote> +When you want to run GEOS in an emulator, you must adjust that emulator so that +it does a "true drive" emulation. Each emulator has its own way of turning that +feature on. +</quote> + +<quote> +VICE even has different ways that depend on which operating system is running +the emulator. +<itemize> +<item>In Windows, you must click on <bf/Options/ (in an always visible menu). + Then, you must click on <bf/True drive emulation/. +<item>In Unix, you must <em/hold down/ the second button on your mouse. Move + the pointer down to <bf/Drive settings/. Then, move the pointer over to + <bf/Enable true drive emulation/. (If there is a check-mark in front of + those words, that feature already is turned on -- then, move the pointer + off of that menu.) Release the mouse button. +</itemize> +</quote> + +Find the <bf/CONVERT/ program on the boot disk [tap the 6-key; then, you +should see its icon in the fourth position on the <bf/deskTop/'s directory +notePad]. Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click +it to run that program. Click on the <bf/Disk/ icon; put the disk with +"<tt/hello1/" into the drive; and, click the <bf/OK/ icon. Use the little +icons under the list of file-names to move through that list until you find +"<tt/hello1/". Click on it; and then, click on the <bf/Convrt/ icon. +<bf/CONVERT/ will ask you to confirm that you choose the correct file; click +<bf/YES/ if you did (or, click <bf/NO/ if you made a mistake). After the +program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will +announce what it did -- click on <bf/OK/. <bf/CONVERT/ will show the file list +again. This time, click on <bf/Quit/. + +(You might need to put the boot disk back into the drive, in order to reload +<bf/deskTop/. Then, you must swap back to the disk with the tutorial program +on it, and click on its disk icon [on the right side of the screen].) + +Now, you must find <bf/hello1/. Click on the lower left-hand corner of the +directory notePad. Look at the eight file-positions on each page until you see +<bf/hello1/. Double-click on its icon. + +The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished +reading it. + + +<sect1>Contributions wanted<p> + +We need your help! Recommended emulators and instructions for other targets +are missing. We suggest that you choose emulators with good compatibility. +Also, being able to run all computers in the target series is good for +target compatibility testing. A machine-language monitor is almost essential +for debugging, but a native debugger could be used, as well. + +Finally, emulators which run on Unix or Windows would help to reach a wider +audience. + +</article> diff --git a/doc/ld65.sgml b/doc/ld65.sgml new file mode 100644 index 000000000..5330a21d9 --- /dev/null +++ b/doc/ld65.sgml @@ -0,0 +1,1114 @@ +<!doctype linuxdoc system> <!-- -*- text-mode -*- --> + +<article> +<title>ld65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>02.12.2000, 02.10.2001 + +<abstract> +The ld65 linker combines object files into an executable file. ld65 is highly +configurable and uses configuration files for high flexibility. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +The ld65 linker combines several object modules created by the ca65 +assembler, producing an executable file. The object modules may be read +from a library created by the ar65 archiver (this is somewhat faster and +more convenient). The linker was designed to be as flexible as possible. +It complements the features that are built into the ca65 macroassembler: + +<itemize> + +<item> Accept any number of segments to form an executable module. + +<item> Resolve arbitrary expressions stored in the object files. + +<item> In case of errors, use the meta information stored in the object files + to produce helpful error messages. In case of undefined symbols, + expression range errors, or symbol type mismatches, ld65 is able to + tell you the exact location in the original assembler source, where + the symbol was referenced. + +<item> Flexible output. The output of ld65 is highly configurable by a config + file. More common platforms are supported by builtin configurations + that may be activated by naming the target system. The output + generation was designed with different output formats in mind, so + adding other formats shouldn't be a great problem. + +</itemize> + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The linker is called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: ld65 [options] module ... +Short options: + -( Start a library group + -) End a library group + -C name Use linker config file + -D sym=val Define a symbol + -L path Specify a library search path + -Ln name Create a VICE label file + -S addr Set the default start address + -V Print the linker version + -h Help (this text) + -m name Create a map file + -o name Name the default output file + -t sys Set the target system + -u sym Force an import of symbol `sym' + -v Verbose mode + -vm Verbose map file + +Long options: + --cfg-path path Specify a config file search path + --config name Use linker config file + --dbgfile name Generate debug information + --define sym=val Define a symbol + --dump-config name Dump a builtin configuration + --end-group End a library group + --force-import sym Force an import of symbol `sym' + --help Help (this text) + --lib file Link this library + --lib-path path Specify a library search path + --mapfile name Create a map file + --module-id id Specify a module id + --obj file Link this object file + --obj-path path Specify an object file search path + --start-addr addr Set the default start address + --start-group Start a library group + --target sys Set the target system + --version Print the linker version +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Here is a description of all the command line options: + +<descrip> + + <label id="option--start-group"> + <tag><tt>-(, --start-group</tt></tag> + + Start a library group. The libraries specified within a group are searched + multiple times to resolve crossreferences within the libraries. Normally, + crossreferences are only resolved within a library, that is the library is + searched multiple times. Libraries specified later on the command line + cannot reference otherwise unreferenced symbols in libraries specified + earlier, because the linker has already handled them. Library groups are + a solution for this problem, because the linker will search repeatedly + through all libraries specified in the group, until all possible open + symbol references have been satisfied. + + + <tag><tt>-), --end-group</tt></tag> + + End a library group. See the explanation of the <tt><ref + id="option--start-group" name="--start-group"></tt> option. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option-m"> + <tag><tt>-m name, --mapfile name</tt></tag> + + This option (which needs an argument that will used as a filename for + the generated map file) will cause the linker to generate a map file. + The map file does contain a detailed overview over the modules used, the + sizes for the different segments, and a table containing exported + symbols. + + + <label id="option-o"> + <tag><tt>-o name</tt></tag> + + The -o switch is used to give the name of the default output file. + Depending on your output configuration, this name may NOT be used as + name for the output file. However, for the builtin configurations, this + name is used for the output file name. + + + <label id="option-t"> + <tag><tt>-t sys, --target sys</tt></tag> + + The argument for the -t switch is the name of the target system. Since this + switch will activate a builtin configuration, it may not be used together + with the <tt><ref id="option-C" name="-C"></tt> option. The following target + systems are currently supported: + + <itemize> + <item>none + <item>module + <item>apple2 + <item>apple2enh + <item>atari + <item>atmos + <item>c16 (works also for the c116 with memory up to 32K) + <item>c64 + <item>c128 + <item>cbm510 (CBM-II series with 40 column video) + <item>cbm610 (all CBM series-II computers with 80 column video) + <item>geos-apple + <item>geos-cbm + <item>lunix + <item>lynx + <item>nes + <item>pet (all CBM PET systems except the 2001) + <item>plus4 + <item>supervision + <item>vic20 + </itemize> + + There are a few more targets defined but neither of them is actually + supported. + + + <tag><tt>-u sym[:addrsize], --force-import sym[:addrsize]</tt></tag> + + Force an import of a symbol. While object files are always linked to the + output file, regardless if there are any references, object modules from + libraries get only linked in if an import can be satisfied by this module. + The <tt/--fore-import/ option may be used to add a reference to a symbol and + as a result force linkage of the module that exports the identifier. + + The name of the symbol may optionally be followed by a colon and an address + size specifier. If no address size is specified, the default address size + for the target machine is used. + + Please note that the symbol name needs to have the internal representation, + meaning you have to prepend an underline for C identifiers. + + + <label id="option-v"> + <tag><tt>-v, --verbose</tt></tag> + + Using the -v option, you may enable more output that may help you to + locate problems. If an undefined symbol is encountered, -v causes the + linker to print a detailed list of the references (that is, source file + and line) for this symbol. + + + <tag><tt>-vm</tt></tag> + + Must be used in conjunction with <tt><ref id="option-m" name="-m"></tt> + (generate map file). Normally the map file will not include empty segments + and sections, or unreferenced symbols. Using this option, you can force the + linker to include all this information into the map file. + + + <label id="option-C"> + <tag><tt>-C</tt></tag> + + This gives the name of an output config file to use. See section 4 for more + information about config files. -C may not be used together with <tt><ref + id="option-t" name="-t"></tt>. + + + <label id="option-D"> + <tag><tt>-D sym=value, --define sym=value</tt></tag> + + This option allows to define an external symbol on the command line. Value + may start with a '$' sign or with <tt/0x/ for hexadecimal values, + otherwise a leading zero denotes octal values. See also the <ref + id="SYMBOLS" name="SYMBOLS section"> in the configuration file. + + + <label id="option--lib-path"> + <tag><tt>-L path, --lib-path path</tt></tag> + + Specify a library search path. This option may be used more than once. It + adds a directory to the search path for library files. Libraries specified + without a path are searched in current directory, in the directory given in + the <tt/LD65_LIB/ environment variable, and in the list of directories + specified using <tt/--lib-path/. + + + <tag><tt>-Ln</tt></tag> + + This option allows you to create a file that contains all global labels and + may be loaded into VICE emulator using the <tt/ll/ (load label) command. You + may use this to debug your code with VICE. Note: Older versions had some + bugs in the label code. If you have problems, please get the latest VICE + version. + + + <label id="option-S"> + <tag><tt>-S addr, --start-addr addr</tt></tag> + + Using -S you may define the default starting address. If and how this + address is used depends on the config file in use. For the builtin + configurations, only the "none", "apple2" and "apple2enh" systems honor an + explicit start address, all other builtin config provide their own. + + + <tag><tt>-V, --version</tt></tag> + + This option print the version number of the linker. If you send any + suggestions or bugfixes, please include this number. + + + <label id="option--cfg-path"> + <tag><tt>--cfg-path path</tt></tag> + + Specify a config file search path. This option may be used more than once. + It adds a directory to the search path for config files. A config file given + with the <tt><ref id="option-C" name="-C"></tt> option that has no path in + its name is searched in the current directory, in the directory given in the + <tt/LD65_CFG/ environment variable, and in the list of directories specified + using <tt/--cfg-path/. + + + <label id="option--dbgfile"> + <tag><tt>--dbgfile name</tt></tag> + + Specify an output file for debug information. Available information will be + written to this file. Using the <tt/-g/ option for the compiler and assembler + will increase the amount of information available. Please note that debug + information generation is currently being developed, so the format of the + file and its contents are subject to change without further notice. + + + <tag><tt>--lib file</tt></tag> + + Links a library to the output. Use this command line option instead of just + naming the library file, if the linker is not able to determine the file + type because of an unusual extension. + + + <tag><tt>--obj file</tt></tag> + + Links an object file to the output. Use this command line option instead + of just naming the object file, if the linker is not able to determine the + file type because of an unusual extension. + + + <label id="option--obj-path"> + <tag><tt>--obj-path path</tt></tag> + + Specify an object file search path. This option may be used more than once. + It adds a directory to the search path for object files. An object file + passed to the linker that has no path in its name is searched in current + directory, in the directory given in the <tt/LD65_OBJ/ environment variable, + and in the list of directories specified using <tt/--obj-path/. + +</descrip> + + + +<sect>Search paths<p> + +Starting with version 2.10 there are now several search paths for files needed +by the linker: One for libraries, one for object files and one for config +files. + + +<sect1>Library search path<p> + +The library search path contains in this order: + +<enum> +<item>The current directory. +<item>A compiled in library path which is often <tt>/usr/lib/cc65/lib</tt> on + Linux systems. +<item>The value of the environment variable <tt/LD65_LIB/ if it is defined. +<item>A subdirectory named <tt/lib/ of the directory defined in the environment + variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt><ref id="option--lib-path" + name="--lib-path"></tt> option on the command line. +</enum> + + +<sect1>Object file search path<p> + +The object file search path contains in this order: + +<enum> +<item>The current directory. +<item>A compiled in directory which is often <tt>/usr/lib/cc65/obj</tt> on + Linux systems. +<item>The value of the environment variable <tt/LD65_OBJ/ if it is defined. +<item>A subdirectory named <tt/obj/ of the directory defined in the environment + variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt><ref id="option--obj-path" + name="--obj-path"></tt> option on the command line. +</enum> + + +<sect1>Config file search path<p> + +The config file search path contains in this order: + +<enum> +<item>The current directory. +<item>A compiled in directory which is often <tt>/usr/lib/cc65/cfg</tt> on + Linux systems. +<item>The value of the environment variable <tt/LD65_CFG/ if it is defined. +<item>A subdirectory named <tt/cfg/ of the directory defined in the environment + variable <tt/CC65_HOME/, if it is defined. +<item>Any directory added with the <tt><ref id="option--cfg-path" + name="--cfg-path"></tt> option on the command line. +</enum> + + + +<sect>Detailed workings<p> + +The linker does several things when combining object modules: + +First, the command line is parsed from left to right. For each object file +encountered (object files are recognized by a magic word in the header, so +the linker does not care about the name), imported and exported +identifiers are read from the file and inserted in a table. If a library +name is given (libraries are also recognized by a magic word, there are no +special naming conventions), all modules in the library are checked if an +export from this module would satisfy an import from other modules. All +modules where this is the case are marked. If duplicate identifiers are +found, the linker issues a warning. + +This procedure (parsing and reading from left to right) does mean, that a +library may only satisfy references for object modules (given directly or from +a library) named <em/before/ that library. With the command line + +<tscreen><verb> + ld65 crt0.o clib.lib test.o +</verb></tscreen> + +the module test.o may not contain references to modules in the library +clib.lib. If this is the case, you have to change the order of the modules +on the command line: + +<tscreen><verb> + ld65 crt0.o test.o clib.lib +</verb></tscreen> + +Step two is, to read the configuration file, and assign start addresses +for the segments and define any linker symbols (see <ref id="config-files" +name="Configuration files">). + +After that, the linker is ready to produce an output file. Before doing that, +it checks its data for consistency. That is, it checks for unresolved +externals (if the output format is not relocatable) and for symbol type +mismatches (for example a zero page symbol is imported by a module as absolute +symbol). + +Step four is, to write the actual target files. In this step, the linker will +resolve any expressions contained in the segment data. Circular references are +also detected in this step (a symbol may have a circular reference that goes +unnoticed if the symbol is not used). + +Step five is to output a map file with a detailed list of all modules, +segments and symbols encountered. + +And, last step, if you give the <tt><ref id="option-v" name="-v"></tt> switch +twice, you get a dump of the segment data. However, this may be quite +unreadable if you're not a developer:-) + + + +<sect>Configuration files<label id="config-files"><p> + +Configuration files are used to describe the layout of the output file(s). Two +major topics are covered in a config file: The memory layout of the target +architecture, and the assignment of segments to memory areas. In addition, +several other attributes may be specified. + +Case is ignored for keywords, that is, section or attribute names, but it is +<em/not/ ignored for names and strings. + + + +<sect1>Memory areas<p> + +Memory areas are specified in a <tt/MEMORY/ section. Lets have a look at an +example (this one describes the usable memory layout of the C64): + +<tscreen><verb> + MEMORY { + RAM1: start = $0800, size = $9800; + ROM1: start = $A000, size = $2000; + RAM2: start = $C000, size = $1000; + ROM2: start = $E000, size = $2000; + } +</verb></tscreen> + +As you can see, there are two ram areas and two rom areas. The names +(before the colon) are arbitrary names that must start with a letter, with +the remaining characters being letters or digits. The names of the memory +areas are used when assigning segments. As mentioned above, case is +significant for these names. + +The syntax above is used in all sections of the config file. The name +(<tt/ROM1/ etc.) is said to be an identifier, the remaining tokens up to the +semicolon specify attributes for this identifier. You may use the equal sign +to assign values to attributes, and you may use a comma to separate +attributes, you may also leave both out. But you <em/must/ use a semicolon to +mark the end of the attributes for one identifier. The section above may also +have looked like this: + +<tscreen><verb> + # Start of memory section + MEMORY + { + RAM1: + start $0800 + size $9800; + ROM1: + start $A000 + size $2000; + RAM2: + start $C000 + size $1000; + ROM2: + start $E000 + size $2000; + } +</verb></tscreen> + +There are of course more attributes for a memory section than just start and +size. Start and size are mandatory attributes, that means, each memory area +defined <em/must/ have these attributes given (the linker will check that). I +will cover other attributes later. As you may have noticed, I've used a +comment in the example above. Comments start with a hash mark (`#'), the +remainder of the line is ignored if this character is found. + + +<sect1>Segments<p> + +Let's assume you have written a program for your trusty old C64, and you would +like to run it. For testing purposes, it should run in the <tt/RAM/ area. So +we will start to assign segments to memory sections in the <tt/SEGMENTS/ +section: + +<tscreen><verb> + SEGMENTS { + CODE: load = RAM1, type = ro; + RODATA: load = RAM1, type = ro; + DATA: load = RAM1, type = rw; + BSS: load = RAM1, type = bss, define = yes; + } +</verb></tscreen> + +What we are doing here is telling the linker, that all segments go into the +<tt/RAM1/ memory area in the order specified in the <tt/SEGMENTS/ section. So +the linker will first write the <tt/CODE/ segment, then the <tt/RODATA/ +segment, then the <tt/DATA/ segment - but it will not write the <tt/BSS/ +segment. Why? Enter the segment type: For each segment specified, you may also +specify a segment attribute. There are four possible segment attributes: + +<tscreen><verb> + ro means readonly + rw means read/write + bss means that this is an uninitialized segment + zp a zeropage segment +</verb></tscreen> + +So, because we specified that the segment with the name BSS is of type bss, +the linker knows that this is uninitialized data, and will not write it to an +output file. This is an important point: For the assembler, the <tt/BSS/ +segment has no special meaning. You specify, which segments have the bss +attribute when linking. This approach is much more flexible than having one +fixed bss segment, and is a result of the design decision to supporting an +arbitrary segment count. + +If you specify "<tt/type = bss/" for a segment, the linker will make sure that +this segment does only contain uninitialized data (that is, zeroes), and issue +a warning if this is not the case. + +For a <tt/bss/ type segment to be useful, it must be cleared somehow by your +program (this happens usually in the startup code - for example the startup +code for cc65 generated programs takes care about that). But how does your +code know, where the segment starts, and how big it is? The linker is able to +give that information, but you must request it. This is, what we're doing with +the "<tt/define = yes/" attribute in the <tt/BSS/ definitions. For each +segment, where this attribute is true, the linker will export three symbols. + +<tscreen><verb> + __NAME_LOAD__ This is set to the address where the + segment is loaded. + __NAME_RUN__ This is set to the run address of the + segment. We will cover run addresses + later. + __NAME_SIZE__ This is set to the segment size. +</verb></tscreen> + +Replace <tt/NAME/ by the name of the segment, in the example above, this would +be <tt/BSS/. These symbols may be accessed by your code. + +Now, as we've configured the linker to write the first three segments and +create symbols for the last one, there's only one question left: Where does +the linker put the data? It would be very convenient to have the data in a +file, wouldn't it? + +<sect1>Output files<p> + +We don't have any files specified above, and indeed, this is not needed in a +simple configuration like the one above. There is an additional attribute +"file" that may be specified for a memory area, that gives a file name to +write the area data into. If there is no file name given, the linker will +assign the default file name. This is "a.out" or the one given with the +<tt><ref id="option-o" name="-o"></tt> option on the command line. Since the +default behaviour is ok for our purposes, I did not use the attribute in the +example above. Let's have a look at it now. + +The "file" attribute (the keyword may also be written as "FILE" if you like +that better) takes a string enclosed in double quotes (`"') that specifies the +file, where the data is written. You may specify the same file several times, +in that case the data for all memory areas having this file name is written +into this file, in the order of the memory areas defined in the <tt/MEMORY/ +section. Let's specify some file names in the <tt/MEMORY/ section used above: + +<tscreen><verb> + MEMORY { + RAM1: start = $0800, size = $9800, file = %O; + ROM1: start = $A000, size = $2000, file = "rom1.bin"; + RAM2: start = $C000, size = $1000, file = %O; + ROM2: start = $E000, size = $2000, file = "rom2.bin"; + } +</verb></tscreen> + +The <tt/%O/ used here is a way to specify the default behaviour explicitly: +<tt/%O/ is replaced by a string (including the quotes) that contains the +default output name, that is, "a.out" or the name specified with the <tt><ref +id="option-o" name="-o"></tt> option on the command line. Into this file, the +linker will first write any segments that go into <tt/RAM1/, and will append +then the segments for <tt/RAM2/, because the memory areas are given in this +order. So, for the RAM areas, nothing has really changed. + +We've not used the ROM areas, but we will do that below, so we give the file +names here. Segments that go into <tt/ROM1/ will be written to a file named +"rom1.bin", and segments that go into <tt/ROM2/ will be written to a file +named "rom2.bin". The name given on the command line is ignored in both cases. + +Assigning an empty file name for a memory area will discard the data written +to it. This is useful, if the memory area has segments assigned that are empty +(for example because they are of type bss). In that case, the linker will +create an empty output file. This may be suppressed by assigning an empty file +name to that memory area. + +The <tt/%O/ sequence is also allowed inside a string. So using + +<tscreen><verb> + MEMORY { + ROM1: start = $A000, size = $2000, file = "%O-1.bin"; + ROM2: start = $E000, size = $2000, file = "%O-2.bin"; + } +</verb></tscreen> + +would write two files that start with the name of the output file specified on +the command line, with "-1.bin" and "-2.bin" appended respectively. Because +'%' is used as an escape char, the sequence "%%" has to be used if a single +percent sign is required. + +<sect1>LOAD and RUN addresses (ROMable code)<p> + +Let us look now at a more complex example. Say, you've successfully tested +your new "Super Operating System" (SOS for short) for the C64, and you +will now go and replace the ROMs by your own code. When doing that, you +face a new problem: If the code runs in RAM, we need not to care about +read/write data. But now, if the code is in ROM, we must care about it. +Remember the default segments (you may of course specify your own): + +<tscreen><verb> + CODE read only code + RODATA read only data + DATA read/write data + BSS uninitialized data, read/write +</verb></tscreen> + +Since <tt/BSS/ is not initialized, we must not care about it now, but what +about <tt/DATA/? <tt/DATA/ contains initialized data, that is, data that was +explicitly assigned a value. And your program will rely on these values on +startup. Since there's no other way to remember the contents of the data +segment, than storing it into one of the ROMs, we have to put it there. But +unfortunately, ROM is not writable, so we have to copy it into RAM before +running the actual code. + +The linker won't copy the data from ROM into RAM for you (this must be done by +the startup code of your program), but it has some features that will help you +in this process. + +First, you may not only specify a "<tt/load/" attribute for a segment, but +also a "<tt/run/" attribute. The "<tt/load/" attribute is mandatory, and, if +you don't specify a "<tt/run/" attribute, the linker assumes that load area +and run area are the same. We will use this feature for our data area: + +<tscreen><verb> + SEGMENTS { + CODE: load = ROM1, type = ro; + RODATA: load = ROM2, type = ro; + DATA: load = ROM2, run = RAM2, type = rw, define = yes; + BSS: load = RAM2, type = bss, define = yes; + } +</verb></tscreen> + +Let's have a closer look at this <tt/SEGMENTS/ section. We specify that the +<tt/CODE/ segment goes into <tt/ROM1/ (the one at $A000). The readonly data +goes into <tt/ROM2/. Read/write data will be loaded into <tt/ROM2/ but is run +in <tt/RAM2/. That means that all references to labels in the <tt/DATA/ +segment are relocated to be in <tt/RAM2/, but the segment is written to +<tt/ROM2/. All your startup code has to do is, to copy the data from its +location in <tt/ROM2/ to the final location in <tt/RAM2/. + +So, how do you know, where the data is located? This is the second point, +where you get help from the linker. Remember the "<tt/define/" attribute? +Since we have set this attribute to true, the linker will define three +external symbols for the data segment that may be accessed from your code: + +<tscreen><verb> + __DATA_LOAD__ This is set to the address where the segment + is loaded, in this case, it is an address in + ROM2. + __DATA_RUN__ This is set to the run address of the segment, + in this case, it is an address in RAM2. + __DATA_SIZE__ This is set to the segment size. +</verb></tscreen> + +So, what your startup code must do, is to copy <tt/__DATA_SIZE__/ bytes from +<tt/__DATA_LOAD__/ to <tt/__DATA_RUN__/ before any other routines are called. +All references to labels in the <tt/DATA/ segment are relocated to <tt/RAM2/ +by the linker, so things will work properly. + +There's a library subroutine called <tt/copydata/ (in a module named +<tt/copydata.s/) that might be used to do actual copying. Be sure to have a +look at it's inner workings before using it! + + +<sect1>Other MEMORY area attributes<p> + +There are some other attributes not covered above. Before starting the +reference section, I will discuss the remaining things here. + +You may request symbols definitions also for memory areas. This may be +useful for things like a software stack, or an i/o area. + +<tscreen><verb> + MEMORY { + STACK: start = $C000, size = $1000, define = yes; + } +</verb></tscreen> + +This will define some external symbols that may be used in your code: + +<tscreen><verb> + __STACK_START__ This is set to the start of the memory + area, $C000 in this example. + __STACK_SIZE__ The size of the area, here $1000. + __STACK_LAST__ This is NOT the same as START+SIZE. + Instead, it it defined as the first + address that is not used by data. If we + don't define any segments for this area, + the value will be the same as START. + __STACK_FILEOFFS__ The binary offset in the output file. This + is not defined for relocatable output file + formats (o65). +</verb></tscreen> + +A memory section may also have a type. Valid types are + +<tscreen><verb> + ro for readonly memory + rw for read/write memory. +</verb></tscreen> + +The linker will assure, that no segment marked as read/write or bss is put +into a memory area that is marked as readonly. + +Unused memory in a memory area may be filled. Use the "<tt/fill = yes/" +attribute to request this. The default value to fill unused space is zero. If +you don't like this, you may specify a byte value that is used to fill these +areas with the "<tt/fillval/" attribute. If there is no "<tt/fillval/" +attribute for the segment, the "<tt/fillval/" attribute of the memory area (or +its default) is used instead. This means that the value may also be used to +fill unfilled areas generated by the assemblers <tt/.ALIGN/ and <tt/.RES/ +directives. + +The symbol <tt/%S/ may be used to access the default start address (that is, +the one defined in the <ref id="FEATURES" name="FEATURES"> section, or the +value given on the command line with the <tt><ref id="option-S" name="-S"></tt> +option). + +To support systems with banked memory, a special attribute named <tt/bank/ is +available. The attribute value is an arbitrary 32 bit integer. The assembler +has a builtin function named <tt/.BANK/ which may be used with an argument +that has a segment reference (for example a symbol). The result of this +function is the value of the bank attribute for the run memory area of the +segment. + + +<sect1>Other SEGMENT attributes<p> + +Segments may be aligned to some memory boundary. Specify "<tt/align = num/" to +request this feature. Num must be a power of two. To align all segments on a +page boundary, use + +<tscreen><verb> + SEGMENTS { + CODE: load = ROM1, type = ro, align = $100; + RODATA: load = ROM2, type = ro, align = $100; + DATA: load = ROM2, run = RAM2, type = rw, define = yes, + align = $100; + BSS: load = RAM2, type = bss, define = yes, align = $100; + } +</verb></tscreen> + +If an alignment is requested, the linker will add enough space to the output +file, so that the new segment starts at an address that is dividable by the +given number without a remainder. All addresses are adjusted accordingly. To +fill the unused space, bytes of zero are used, or, if the memory area has a +"<tt/fillval/" attribute, that value. Alignment is always needed, if you have +used the <tt/.ALIGN/ command in the assembler. The alignment of a segment +must be equal or greater than the alignment used in the <tt/.ALIGN/ command. +The linker will check that, and issue a warning, if the alignment of a segment +is lower than the alignment requested in an <tt/.ALIGN/ command of one of the +modules making up this segment. + +For a given segment you may also specify a fixed offset into a memory area or +a fixed start address. Use this if you want the code to run at a specific +address (a prominent case is the interrupt vector table which must go at +address $FFFA). Only one of <tt/ALIGN/ or <tt/OFFSET/ or <tt/START/ may be +specified. If the directive creates empty space, it will be filled with zero, +of with the value specified with the "<tt/fillval/" attribute if one is given. +The linker will warn you if it is not possible to put the code at the +specified offset (this may happen if other segments in this area are too +large). Here's an example: + +<tscreen><verb> + SEGMENTS { + VECTORS: load = ROM2, type = ro, start = $FFFA; + } +</verb></tscreen> + +or (for the segment definitions from above) + +<tscreen><verb> + SEGMENTS { + VECTORS: load = ROM2, type = ro, offset = $1FFA; + } +</verb></tscreen> + +The "<tt/align/", "<tt/start/" and "<tt/offset/" attributes change placement +of the segment in the run memory area, because this is what is usually +desired. If load and run memory areas are equal (which is the case if only the +load memory area has been specified), the attributes will also work. There is +also an "<tt/align_load/" attribute that may be used to align the start of the +segment in the load memory area, in case different load and run areas have +been specified. There are no special attributes to set start or offset for +just the load memory area. + +A "<tt/fillval/" attribute may not only be specified for a memory area, but +also for a segment. The value must be an integer between 0 and 255. It is used +as fill value for space reserved by the assemblers <tt/.ALIGN/ and <tt/.RES/ +commands. It is also used as fill value for space between sections (part of a +segment that comes from one object file) caused by alignment, but not for +space that preceeds the first section. + +To suppress the warning, the linker issues if it encounters a segment that is +not found in any of the input files, use "<tt/optional=yes/" as additional +segment attribute. Be careful when using this attribute, because a missing +segment may be a sign of a problem, and if you're suppressing the warning, +there is no one left to tell you about it. + +<sect1>The FILES section<p> + +The <tt/FILES/ section is used to support other formats than straight binary +(which is the default, so binary output files do not need an explicit entry +in the <tt/FILES/ section). + +The <tt/FILES/ section lists output files and as only attribute the format of +each output file. Assigning binary format to the default output file would +look like this: + +<tscreen><verb> + FILES { + %O: format = bin; + } +</verb></tscreen> + +The only other available output format is the o65 format specified by Andre +Fachat (see the <htmlurl url="http://www.6502.org/users/andre/o65/fileformat.html" +name="6502 binary relocation format specification">). It is defined like this: + +<tscreen><verb> + FILES { + %O: format = o65; + } +</verb></tscreen> + +The necessary o65 attributes are defined in a special section labeled +<tt/FORMAT/. + + + +<sect1>The FORMAT section<p> + +The <tt/FORMAT/ section is used to describe file formats. The default (binary) +format has currently no attributes, so, while it may be listed in this +section, the attribute list is empty. The second supported format, +<htmlurl url="http://www.6502.org/users/andre/o65/fileformat.html" name="o65">, +has several attributes that may be defined here. + +<tscreen><verb> + FORMATS { + o65: os = lunix, version = 0, type = small, + import = LUNIXKERNEL, + export = _main; + } +</verb></tscreen> + + + +<sect1>The FEATURES section<label id="FEATURES"><p> + +In addition to the <tt/MEMORY/ and <tt/SEGMENTS/ sections described above, the +linker has features that may be enabled by an additional section labeled +<tt/FEATURES/. + + +<sect2>The CONDES feature<p> + +<tt/CONDES/ is used to tell the linker to emit module constructor/destructor +tables. + +<tscreen><verb> + FEATURES { + CONDES: segment = RODATA, + type = constructor, + label = __CONSTRUCTOR_TABLE__, + count = __CONSTRUCTOR_COUNT__; + } +</verb></tscreen> + +The <tt/CONDES/ feature has several attributes: + +<descrip> + + <tag><tt>segment</tt></tag> + + This attribute tells the linker into which segment the table should be + placed. If the segment does not exist, it is created. + + + <tag><tt>type</tt></tag> + + Describes the type of the routines to place in the table. Type may be one of + the predefined types <tt/constructor/, <tt/destructor/, <tt/interruptor/, or + a numeric value between 0 and 6. + + + <tag><tt>label</tt></tag> + + This specifies the label to use for the table. The label points to the start + of the table in memory and may be used from within user written code. + + + <tag><tt>count</tt></tag> + + This is an optional attribute. If specified, an additional symbol is defined + by the linker using the given name. The value of this symbol is the number + of entries (<em/not/ bytes) in the table. While this attribute is optional, + it is often useful to define it. + + + <tag><tt>order</tt></tag> + + Optional attribute that takes one of the keywords <tt/increasing/ or + <tt/decreasing/ as an argument. Specifies the sorting order of the entries + within the table. The default is <tt/increasing/, which means that the + entries are sorted with increasing priority (the first entry has the lowest + priority). "Priority" is the priority specified when declaring a symbol as + <tt/.CONDES/ with the assembler, higher values mean higher priority. You may + change this behaviour by specifying <tt/decreasing/ as the argument, the + order of entries is reversed in this case. + + Please note that the order of entries with equal priority is undefined. + + <tag><tt>import</tt></tag> + + This attribute defines a valid symbol name, that is added as an import + to the modules defining a constructor/desctructor of the given type. + This can be used to force linkage of a module if this module exports the + requested symbol. + +</descrip> + +Without specifying the <tt/CONDES/ feature, the linker will not create any +tables, even if there are <tt/condes/ entries in the object files. + +For more information see the <tt/.CONDES/ command in the <htmlurl +url="ca65.html" name="ca65 manual">. + + +<sect2>The STARTADDRESS feature<p> + +<tt/STARTADDRESS/ is used to set the default value for the start address, +which can be referenced by the <tt/%S/ symbol. The builtin default for the +linker is $200. + +<tscreen><verb> + FEATURES { + # Default start address is $1000 + STARTADDRESS: default = $1000; + } +</verb></tscreen> + +Please note that order is important: The default start address must be defined +<em/before/ the <tt/%S/ symbol is used in the config file. This does usually +mean, that the <tt/FEATURES/ section has to go to the top of the config file. + + + +<sect1>The SYMBOLS section<label id="SYMBOLS"><p> + +The configuration file may also be used to define symbols used in the link +stage or to force symbols imports. This is done in the SYMBOLS section. The +symbol name is followed by a colon and symbol attributes. + +The following symbol attributes are supported: + +<descrip> + + <tag><tt>addrsize</tt></tag> + + The <tt/addrsize/ attribute specifies the address size of the symbol and + may be one of +<itemize> + <item><tt/zp/, <tt/zeropage/ or <tt/direct/ + <item><tt/abs/, <tt/absolute/ or <tt/near/ + <item><tt/far/ + <item><tt/long/ or <tt/dword/. +</itemize> + +Without this attribute, the default address size is <tt/abs/. + + <tag><tt>type</tt></tag> + + This attribute is mandatory. Its value is one of <tt/export/, <tt/import/ or + <tt/weak/. <tt/export/ means that the symbol is defined and exported from + the linker config. <tt/import/ means that an import is generated for this + symbol, eventually forcing a module that exports this symbol to be included + in the output. <tt/weak/ is similar as <tt/export/. However, the symbol is + only defined if it is not defined elsewhere. + + <tag><tt>value</tt></tag> + + This must only be given for symbols of type <tt/export/ or <tt/weak/. It + defines the value of the symbol and may be an expression. + +</descrip> + +The following example defines the stack size for an application, but allows +the programmer to override the value by specifying <tt/--define +__STACKSIZE__=xxx/ on the command line. + +<tscreen><verb> + SYMBOLS { + # Define the stack size for the application + __STACKSIZE__: type = weak, value = $800; + } +</verb></tscreen> + + + +<sect1>Builtin configurations<p> + +The builtin configurations are part of the linker source. They can be retrieved +with <tt/--dump-config/ and don't have a special format. So if you need a +special configuration, it's a good idea to start with the builtin configuration +for your system. In a first step, just replace <tt/-t target/ by <tt/-C +configfile/. Then go on and modify the config file to suit your needs. + + + +<sect1>Secondary configurations<p> + +Several machine specific binary packages are distributed together with secondary +configurations (in the cfg directory). These configurations can be used with +<tt/-C configfile/ too. + + + +<sect>Special segments<p> + +The builtin config files do contain segments that have a special meaning for +the compiler and the libraries that come with it. If you replace the builtin +config files, you will need the following information. + +<sect1>INIT<p> + +The INIT segment is used for initialization code that may be reused once +execution reaches main() - provided that the program runs in RAM. You +may for example add the INIT segment to the heap in really memory +constrained systems. + +<sect1>LOWCODE<p> + +For the LOWCODE segment, it is guaranteed that it won't be banked out, so it +is reachable at any time by interrupt handlers or similar. + +<sect1>STARTUP<p> + +This segment contains the startup code which initializes the C software stack +and the libraries. It is placed in its own segment because it needs to be +loaded at the lowest possible program address on several platforms. + +<sect1>ZPSAVE<p> + +The ZPSAVE segment contains the original values of the zeropage locations used +by the ZEROPAGE segment. It is placed in its own segment because it must not be +initialized. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the linker, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +ld65 (and all cc65 binutils) are (C) Copyright 1998-2005 Ullrich von +Bassewitz. For usage of the binaries and/or sources the following +conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> diff --git a/doc/library.sgml b/doc/library.sgml new file mode 100644 index 000000000..29a8ca063 --- /dev/null +++ b/doc/library.sgml @@ -0,0 +1,251 @@ +<!doctype linuxdoc system> + +<article> + +<title>cc65 Library Overview +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2000-12-02, 2002-11-26 + +<abstract> +An overview over the runtime and C libraries that come with the cc65 compiler, +including a discussion of the differences to the ISO standard. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains a short overview of the libraries available for the cc65 C +compiler. Please have a look at the <htmlurl url="funcref.html" name="function +reference"> for a list function by function. Since the function reference is +not complete (I'm working on that) it may happen that you don't find a +specific function. In this case, have a look into the header files. All +functions, that are not defined by the ISO C standard have a short comment in +the headers, explaining their use. + + + +<sect>ISO C compatible library<p> + +The C library contains a large subset of the ISO C library. Functions are +usually missing in areas, where there is no support on typical 6502 systems. +Wide character sets are an example for this. + +I will not go into detail about the ISO functions. If a function is not +mentioned here explicitly, expect it to be available and to behave as defined +in the C standard. + +Functions that are <em/not/ available: + +<itemize> + <item><tt>tmpfile/tmpnam</tt> + <p> + <item><tt>system</tt> + <p> + <item>All functions that handle floating point numbers in some manner. + <p> + <item>The <tt/ldiv/ function (cc65 is currently not able to return structs + with a size not equal to 1, 2 or 4 bytes by value). + <p> + <item>All functions handling wide character strings. + <p> + <item>Signals and all related functions (having <tt/SIGSEGV/ would be + cool:-) + <p> + <item><tt>setbuf/setvbuf</tt> +</itemize> + +Functions not available on all supported systems: + +<itemize> + <item><tt>fopen/fread/fwrite/fclose/fputs/fgets/fscanf</tt>: The functions + are built on open/read/write/close. These latter functions are not available + on all systems. + <p> + <item><tt>ftell/fseek/fgetpos/fsetpos</tt>: Support depends on the + capabilities of the target machine. + <p> + <item><tt>rename/remove/rewind</tt>: Support depends on the capabilities of + the target machine. + <p> + <item><tt>time</tt>: Since many of the supported systems do not have a real + time clock, which means that the <tt/time/ function is not available. Please + note that the other functions from <tt/time.h/ <em/are/ available. +</itemize> + + +Functions that are limited in any way: + +<itemize> + <item><tt>strcspn/strpbrk/strspn</tt>: These functions have a length + limitation of 256 for the second string argument. Since this string gives a + character set, and there are only 256 distinct characters, this shouldn't be + a problem. + <p> + <item><tt>getenv</tt>: Since there is no such thing as an environment on all + supported systems, the <tt/getenv/ function will always return a <tt/NULL/ + pointer. + <p> + <item><tt>locale</tt>: There is no other locale than the "C" locale. The + native locale is identical to the "C" locale. +</itemize> + + +In addition to these limitations, some more functions are limited if inlined +versions are requested by using -Os: + +<itemize> + <item>The <tt/strlen/ function only works for strings with a maximum length + of 255 characters. + <p> + <item>The <tt/isxxx/ character classification functions from + <tt/<ctype.h>/ will give unpredictable results if the argument is not + in character range (0..255). This limitation may be removed by #undef'ing + the function name (when using <tt/-Os/, the functions are actually macros + that expand to inline assembler code, but the real functions are still + available if the macro definition is removed). +</itemize> + + + +<sect>CPU specific stuff - 6502.h<p> + +The header file 6502.h contains some functions that make only sense with the +6502 CPU. Examples are macros to insert more or less useful instructions into +your C code, or a function to call arbitrary machine language subroutines, +passing registers in and out. + + + +<sect>Target specific stuff<p> + +For each supported system there's a header file that contains calls or defines +specific for this system. So, when programming for the C64, include c64.h, for +the C128, include c128.h and so on. To make the task for the Commodore systems +easier, there is also a header file named cbm.h that will define stuff common +for all CBM systems, and include the header file for the specific target +system. + +The header files contain + +<itemize> + + <item>Defines for special keys (like function keys) + + <item>Defines for special characters (like the graphics characters) + + <item>Variables with a fixed address in memory that may be used to access + special hardware. For the C64 and C128 there is a variable struct named + <tt/SID/. Writing to the fields of this struct will write to the SID device + instead. Using these variables will make your program more readable and more + portable. Don't fear ineffective code when using these variables, the + compiler will translate reads and writes to these structs into direct memory + accesses. + + <item>Other routines that make only sense for a specific system. One example + are routines to write memory locations in the system bank for the CBM PET-II + family. + +</itemize> + + +<sect>Direct console I/O - <tt/conio.h/<p> + +The <tt/conio.h/ header file contains a large set of functions that do screen +and keyboard I/O. The functions will write directly to the screen or poll the +keyboard directly with no more help from the operating system than needed. +This has some disadvantages, but on the other side it's fast and reasonably +portable. conio implementations exist for the following targets: + + <itemize> + <item>apple2 + <item>apple2enh + <item>atari + <item>atmos + <item>c16 (works also for the c116 with up to 32K memory) + <item>c64 + <item>c128 + <item>plus4 (or expanded c16/c116) + <item>cbm510 (40 column video) + <item>cbm610 (all CBM series-II computers with 80 column video) + <item>geos-apple + <item>geos-cbm + <item>nes + <item>pet (all CBM PET systems except the 2001) + <item>vic20 + </itemize> + +The conio.h header file does also include the system specific header files +which define constants for special characters and keys. + + + +<sect>Using the joystick - <tt/joystick.h/<p> + +For systems that have a joystick, <tt/joystick.h/ will define a subroutine to +read the current value, including constants to evaluate the result of this +function. To help in writing portable code, the header file will define the +symbol <tt/__JOYSTICK__/ on systems that have a joystick. + + + +<sect>Using a mouse - <tt/mouse.h/<p> + +Some target machines support a mouse. Mouse support is currently available for +the following targets: + + <itemize> + <item>apple2 + <item>apple2enh + <item>atari + <item>c64 + <item>c128 + <item>cbm510 + </itemize> + +The available functions are declared in <tt/mouse.h/ To help writing portable +code, the header file will define the symbol <tt/__MOUSE__/ in systems that +support a mouse. + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +This C runtime library implementation for the cc65 compiler is (C) +Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries +and/or sources the following conditions do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/lynx.sgml b/doc/lynx.sgml new file mode 100644 index 000000000..48c3d7d4a --- /dev/null +++ b/doc/lynx.sgml @@ -0,0 +1,360 @@ +<!doctype linuxdoc system> + +<article> + +<title>Atari Lynx specific information for cc65 +<author>Karri Kaksonen, <htmlurl url="mailto:karri@sipo.fi" name="karri@sipo.fi"> +Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2011-04-01 + +<abstract> +An overview over the Atari Lynx runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Atari Lynx runtime system as it comes +with the cc65 C compiler. It describes the memory layout, Lynx specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that Lynx specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Building your first Hello World application<p> + +Here is a small traditional Hello World program for the Atari Lynx. + +<tscreen><verb> +#include <lynx.h> +#include <tgi.h> +#include <6502.h> + +void main(void) { + tgi_install(tgi_static_stddrv); + tgi_init(); + CLI(); + while (tgi_busy()) + ; + tgi_clear(); + tgi_setcolor(COLOR_GREEN); + tgi_outtextxy(0, 0, "Hello World"); + tgi_updatedisplay(); + while (1) + ; +} +</verb></tscreen> + +The lynx.h contains all kind of system dependent things. + +The tgi.h contains the graphics driver functions. + +The 6502.h is needed for executing the CLI() command. + +As the Atari Lynx does not have ASCII characters available you need to use +the Tiny Graphics Interface library for producing letters on the screen. + +The cc65 compiler suite has a graphics library called "Tiny Graphics +Interface". This interface has some relocatable code. In order to use this +in your own program you need to load it at run time. + +Unfortunately the Lynx does not have a disk drive from where to load it. +Therefore you must already load it at compile time. The easiest way is to +automatically link it in statically from the Lynx C library. + +<tscreen><verb> +cl65 -t lynx -o game.lnx main.c +</verb></tscreen> + +This will create a bootable cart image called game.lnx + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Lynx target +is a cart image. By specifying the config file lynx-bll.cfg the linker will +generate BLL download compatible binary files. + +It is of course possible to change this behaviour by using a modified startup +file and linker config. + +The bootloader used in the cc65 lynx library uses a very minimal bootloader +that does not check the cart or show a title screen. + +The advantage of this bootloader is that it allows creation of cart images to +many common formats. + +Cart sizes +<tscreen><verb> +Block size Rom size Description +512 bytes 128k Standard old games like Warbirds +1024 bytes 256k Most common format for homebrew. Also newer games like Lemmings +2048 bytes 512k Largest games like EOTB +</verb></tscreen> + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and the +kernal enabled, which gives a usable memory range of $200 - $C037. + +Special locations: +<tscreen><verb> + 0000 - 00FF Zero page + 0100 - 01FF Machine stack + + A058 - C037 Collision buffer + C038 - E017 Screen buffer 1 + E018 - FFF7 Screen buffer 0 + FFF8 - FFFF Hardware vectors +</verb></tscreen> + +<descrip> + <tag/Text screen/ + No conio support is currently available for the Lynx. + + <tag/Keyboard/ + The Lynx "flabode" keys, Opt 1, Pause and Opt 2 are implemented using the + conio interface. The only characters the keyboard is able to produce are + 'R' for Restart (Opt 1 + Pause), 'F' for flip (Opt 2 + Pause), + 'P' for pause, '1' for Opt 1, '2' for Opt 2, '3' for Opt 1 + Opt 2 and + '?' for all keys down at the same time. + + <tag/Stack/ + The C runtime stack is located at $C037 (or $A057 if collision + detection is enabled) and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + + <tag/Screen/ + The collision detection screen is at $A058 if it is enabled. The + double buffered screens are at $C038 and $E018. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Lynx specific code may use the <tt/lynx.h/ header file. + + +<sect1>Lynx specific functions<p> + +<itemize> +<item>lynx_eeprom_erase +<item>lynx_eeprom_read +<item>lynx_eeprom_write +<item>lynx_eeread +<item>lynx_eewrite +<item>lynx_exec +<item>lynx_load +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/lynx.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/MIKEY/</tag> + The <tt/MIKEY/ structure allows access to MIKEY chip. See the <tt/_mikey.h/ + header file located in the include directory for the declaration of the + structure. + + <tag><tt/SUZY/</tag> + The <tt/SUZY/ structure allows access to SUZY chip. See the <tt/_suzy.h/ + header file located in the include directory for the declaration of the + structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/lynx-160-102-16.tgi (lynx_160_102_16)/</tag> + A TGI driver for the standard graphics mode (160×102 in 16 colors). + + The TGI driver is implemented as an interrupt driven dual buffering device. + To use it as a single-buffer device set draw page and view page to the same + value 0 or 1; + + The TGI driver has a few Lynx-specific extensions. + + Calling tgi_sprite(spr) or tgi_ioctl(0, spr) will display a standard Lynx + sprite on screen. + + Calling tgi_flip() or tgi_ioctl(1, 0) will do a flip screen. + + Calling tgi_setbgcolor(bgcolor) or tgi_ioctl(2, bgindex) will set the text + background color to the index defined by bgindex. If bgindex is 0 then the + background color is transparent. + + To set the framerate of the display hardware call tgi_setframerate(rate) or + tgi_ioctl(3, rate). The supported framerates are 50, 60 and 75 frames per + second. Actually there is no real reason to use anything else than 75 frames + per second. + + To check if the drawing engine is busy with the previous swap you can + call tgi_busy or tgi_ioctl(4, 0). It returns 0 if idle and 1 if busy + + To update displays you can call tgi_updatedisplay() or tgi_ioctl(4, 1) it + will wait for the next VBL interrupt and set the draw buffer to the + view buffer. The draw buffer is also changed to (drawbuffer xor 1). + + You can also enable or disable collision detection by a call to + tgi_setcollisiondetection(active) or tgi_ioctl(5, active). The collision + result is located before the sprite structure by default in this driver. + + In order to reserve memory for the collision detection buffer you need to + specify lynx-coll.cfg as the configuration file to the linker. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Lynx. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/lynx-stdjoy.joy (lynx_stdjoy)/</tag> + A joystick driver for the standard buttons. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Lynx. + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/lynx-comlynx.ser (lynx_comlynx)/</tag> + A serial driver for the ComLynx port. + + The ComLynx port has Tx and Rx wired together. Every byte is sent + to all connected Lynxes. Only one Lynx can send at a time. There is no + protocol created for communication. You are on your own. + + If the Lynx returns framing error then it is likely that another Lynx is + sending data at the same time. + + The Lynx can also send a break and receive a break. The Lynx break is + recognized if the bit is down for 24 bit cycles or more. + + To send a break you just set the break bit. The length of the break depends + on how long this bit is down. + + The driver supports the baudrates: + <itemize> + <item>62500 + <item>31250 + <item>9600 + <item>7200 + <item>4800 + <item>3600 + <item>2400 + <item>1800 + <item>1200 + <item>600 + <item>300 + <item>150 + <item>134.5 + <item>110 + <item>75 + </itemize> + The parity bit supports MARK and SPACE. It also supports EVEN and ODD parity + but the parity bit is included in the calculation. Most of us don't want it + this way. But there is nothing we can do about it. + + The Lynx hardware will always check parity on incoming traffic. Currently + the driver cannot receive data from standard PC's due to this parity bug. + For working with Lynx to Lynx communication use EVEN parity. + + To send data to standard PC's use MARK or SPACE as parity setting. + + There is always only one stop bit. And the data length is always 8 bits. + + We have no handshaking available. Even software handshake is impossible + as ComLynx has only one wire for the data. + + Both transmit and receive are interrupt driven. + +</descrip><p> + + +<sect>Limitations<p> + + + +<sect>Cart access<p> + +At this point in time there is no support for the cart filesystem yet. I have +a <tt/lynx-cart-demo/ example project that uses an interrupt driven display, +has support for the cart filesystem and an abcmusic sound module. + +At some point in time we may find a way to rewrite these to fit the way the +cc65 drivers require. But for the time being you can create less portable +applications using these Lynx specific modules in <tt/lynx-cart-demo/. + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/nes.sgml b/doc/nes.sgml new file mode 100644 index 000000000..c66b1f2ba --- /dev/null +++ b/doc/nes.sgml @@ -0,0 +1,197 @@ +<!doctype linuxdoc system> + +<article> + +<title>Nintendo Entertainment System specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2005-07-17 + +<abstract> +An overview over the NES runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the NES runtime system as it comes +with the cc65 C compiler. It describes the memory layout, NES specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that NES specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the NES target +is a machine language program with an INES cartridge header. It is of course +possible to change this behaviour by using a modified startup file and linker +config. + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and a +CHR bank enabled, which gives a usable memory range of $8000 - $FFF3. +All boot ROM entry points may be called directly without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at VRAM $2000. + + <tag/Stack/ + The C runtime stack is located at $7FFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing NES specific code may use the <tt/nes.h/ header file. + + +<sect1>NES specific functions<p> + +<itemize> +<item>waitvblank +<item>get_tv +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/nes.inc/ include file do +allow access to hardware located in the address space. + +<descrip> + + <tag><tt/PPU/</tag> + The <tt/PPU/ defines allow access to the PPU chip. + + <tag><tt/APU/</tag> + The <tt/APU/ defines allow access to the APU chip. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +All drivers must be statically linked because no file I/O is available. +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +<descrip> + + <tag><tt/nes-64-56-2.tgi (nes_64_56_2)/</tag> + This driver features a resolution of 64×56 with 2 colors using the + CHR bank. + +</descrip><p> + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the NES. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/nes-stdjoy.joy (nes_stdjoy)/</tag> + A joystick driver for the standard four buttons joypad is available. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the NES. + + +<sect1>RS232 device drivers<p> + +No serial drivers are currently available for the NES. + + + +<sect>Limitations<p> + +<sect1>Disk I/O<p> + +The existing library for the NES doesn't implement C file +I/O. There are no hacks for the <tt/read()/ and <tt/write()/ routines. + +To be more concrete, this limitation means that you cannot use any of the +following functions (and a few others): + +<itemize> +<item>fclose +<item>fopen +<item>fread +<item>fprintf +<item>fputc +<item>fscanf +<item>fwrite +<item>... +</itemize> + + + +<sect>Other hints<p> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + + + diff --git a/doc/od65.sgml b/doc/od65.sgml new file mode 100644 index 000000000..2668b0b86 --- /dev/null +++ b/doc/od65.sgml @@ -0,0 +1,224 @@ +<!doctype linuxdoc system> + +<article> +<title>od65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2010-07-30 + +<abstract> +od65 is the object file dump utility. It is able to output most parts of +<htmlurl url="ca65.html" name="ca65"> generated object files in readable form. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + + +<sect>Overview<p> + +od65 is an object file dump utility. It is able to output most parts of +<htmlurl url="ca65.html" name="ca65"> generated object files in readable form. +Since the contents and format of the object files are not documented +elsewhere and may change at any time, this tool is a portable way to look at +the contents. + +Apart from curiosity, most people don't need to use this tool. + + + +<sect>Usage<p> + +The od65 utility dumps contents of one or more ca65 generated object file to +standard output. It has no cross-version compatibility, so you have to use +a version that matches the version of ca65 used to create the object files. + + +<sect1>Command line option overview<p> + +The program may be called as follows: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: od65 [options] file [options] [file] +Short options: + -h Help (this text) + -H Dump the object file header + -S Dump segments sizes + -V Print the version number and exit + +Long options: + --dump-all Dump all object file information + --dump-dbgsyms Dump debug symbols + --dump-exports Dump exported symbols + --dump-files Dump the source files + --dump-header Dump the object file header + --dump-imports Dump imported symbols + --dump-lineinfo Dump line information + --dump-options Dump object file options + --dump-segments Dump the segments in the file + --dump-segsize Dump segments sizes + --help Help (this text) + --version Print the version number and exit +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<label id="cmdline-opt-detail"><p> + +Here is a description of all the command line options: + +<descrip> + + <tag><tt>--dump-all</tt></tag> + + This will output all information, od65 is able to process. The option is a + shortcut for specifying all the other <tt/--dump/ options. + + + <tag><tt>--dump-dbgsyms</tt></tag> + + Dump all debug symbols contained in the object file. + + + <tag><tt>--dump-exports</tt></tag> + + Dump all exported symbols contained in the object file. + + + <tag><tt>--dump-files</tt></tag> + + Dump the file table contained in the object file. + + + <tag><tt>-H, --dump-header</tt></tag> + + Dump the object file header. + + + <tag><tt>--dump-imports</tt></tag> + + Dump the list of imported symbols contained in the object file. + + + <tag><tt>--dump-lineinfo</tt></tag> + + Dump the line info contained in the object file. + + + <tag><tt>--dump-segments</tt></tag> + + Dump the list of segments contained in the object file. + + + <tag><tt>--dump-scopes</tt></tag> + + Dump the scope (lexical level) information contained in the object file. + + + <tag><tt>-S, --dump-segsize</tt></tag> + + Dump the sizes of all segments contained in the object file. This option is + quite useful to determine the effect of measures that increase or decrease + code size. + + + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <tag><tt>-V, --version</tt></tag> + + Print the version number of the compiler. When submitting a bug report, + please include the operating system you're using, and the compiler + version. +</descrip> + + +<sect>Input and output<p> + +The converter will read one or more object files per invocation and write the +contents in readable format to standard output. Please note that you need to +specify any of the <tt/--dump/ options listed <ref id="cmdline-opt-detail" +name="above">, otherwise no useful output will be generated. + +Example output for the command +<tscreen><verb> +od65 --dump-header --dump-files t.o +</verb></tscreen> +<tscreen><verb> +t.o: + Header: + Magic: 0x616E7A55 + Version: 12 + Flags: 0x0001 (OBJ_FLAGS_DBGINFO) + Options: + Offset: 88 + Size: 9 + Files: + Offset: 97 + Size: 10 + Segments: + Offset: 107 + Size: 101 + Imports: + Offset: 208 + Size: 1 + Exports: + Offset: 209 + Size: 1 + Debug symbols: + Offset: 210 + Size: 55 + Line infos: + Offset: 265 + Size: 1 + String pool: + Offset: 266 + Size: 80 + Files: + Count: 1 + Index: 0 + Name: "t.s" + Size: 402 + Modification time: 1280498435 (Fri Jul 30 16:00:35 2010) +</verb></tscreen> + + +<sect>Bugs/Feedback<p> + +If you have problems using the converter, if you find any bugs, or if you're +doing something interesting with the code, I would be glad to hear from you. +Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>Copyright<p> + +od65 is (C) Copyright 2000-2009, Ullrich von Bassewitz. For usage of the +binaries and/or sources the following conditions apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> + diff --git a/doc/pet.sgml b/doc/pet.sgml new file mode 100644 index 000000000..35e794db5 --- /dev/null +++ b/doc/pet.sgml @@ -0,0 +1,261 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore PET specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2005-05-24 + +<abstract> +An overview over the PET runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the PET runtime system as it comes with the +cc65 C compiler. It describes the memory layout, PET specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that PET specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the PET target +is a machine language program with a one line BASIC stub, which calls the +machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area and the +kernal and BASIC ROM enabled, which gives a usable memory range of +$0400 - $7FFF (32KB machine). +All ROM entry points may be called directly without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $8000. + + <tag/Stack/ + The C runtime stack is located at $7FFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing PET specific code may use the <tt/pet.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/pet.h/ and declares several functions +common to all CBM platforms. + + +<sect1>PET specific functions<p> + +There are currently no special PET functions. + + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/pet.h/ header file do allow +access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/PIA1, PIA2/</tag> + Access to the two PIA (peripheral interface adapter) chips is available via + the <tt/PIA1/ and <tt/PIA2/ variables. The structure behind these variables + is explained in <tt/_pia.h/. + + <tag><tt/VIA/</tag> + The <tt/VIA/ structure allows access to the VIA (versatile interface + adapter). See the <tt/_6522.h/ header file located in the include + directory for the declaration of the structure. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the PET. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the PET. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/pet-ptvjoy.joy (pet_ptvjoy)/</tag> + Driver for the Protovision 4-player adapter contributed by Groepaz. See + <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and + building instructions. Up to two joysticks are supported. + + <tag><tt/pet-stdjoy.joy (pet_stdjoy)/</tag> + Driver for the standard PET userport joystick. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the PET. + + +<sect1>RS232 device drivers<p> + +No serial drivers are currently available for the PET. + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the PET uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + +<sect1>Using extended memory<p> + +The extended memory at $9000 of the CBM 8x96 may be added to the heap by using +the following code: + +<tscreen><verb> + /* Check for the existence of RAM */ + if (PEEK(0x9000) == POKE(0x9000, PEEK(0x9000)+1)) { + /* Add it to the heap */ + _heapadd ((void *) 0x9000, 0x2000); + } +</verb></tscreen> + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/plus4.sgml b/doc/plus4.sgml new file mode 100644 index 000000000..eefb85e21 --- /dev/null +++ b/doc/plus4.sgml @@ -0,0 +1,270 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore Plus/4 specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2003-12-14 + +<abstract> +An overview over the Plus/4 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Plus/4 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, Plus/4 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that Plus/4 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + +Since the Plus/4 and the Commodore 16/116 are almost identical (the latter are +missing the 6551 ACIA and do only have 16KB of memory), the <htmlurl +url="c16.html" name="C16 documentation"> is also worth a look. The difference +between both cc65 targets is that the Plus/4 runtime uses banking to support +full 64K RAM, while the C16 does not use banking and supports up to 32K RAM. +Because banking is not needed, most C16 programs will be somewhat smaller than +the same program compiled for the Plus/4. However, programs compiled for the +C16 will always run on the Plus/4, while the reverse is not necessarily true. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Plus/4 +target is a machine language program with a one line BASIC stub, which calls +the machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the kernal and basic +banked out. This gives a usable memory range of $1000 - $FD00. +Having the kernal and basic ROMs banked out means, that no ROM entry points +may be called directly from user code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $C00 (as in the standard setup). + + <tag/Color RAM/ + The color RAM is located at $800 (standard location). + + <tag/Stack/ + The C runtime stack is located at $FCFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Plus/4 specific code may use the <tt/plus4.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/plus4.h/ and declares several functions +common to all CBM platforms. + +Please note that most of the header file declarations from the <tt/plus4.h/ +header file are shared between the C16 and Plus/4 configurations. For this +reason, most of it is located in a common header file named <tt/cbm264.h/. + + + +<sect1>Plus/4 specific functions<p> + +There are currently no special Plus/4 functions. + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/plus4.h/ header file do +allow access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/TED/</tag> + The <tt/TED/ structure allows access to the TED chip. See the + <tt/_ted.h/ header file located in the include directory for the + declaration of the structure. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the Plus/4 at $0800. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the Plus/4. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Plus/4. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/plus4-stdjoy.joy (plus4_stdjoy)/</tag> + Supports up to two joysticks connected to the standard joysticks port of + the Plus/4. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +Currently no drivers available (in fact, the API for loadable mouse drivers +does not exist). + + +<sect1>RS232 device drivers<p> + +<descrip> + + <tag><tt/plus4-stdser.ser (plus4_stdser)/</tag> + Driver for the 6551 ACIA chip built into the Plus/4. Supports up to 19200 + baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note + that because of the peculiarities of the 6551 chip transmits are not + interrupt driven, and the transceiver blocks if the receiver asserts flow + control because of a full buffer. + + You need an adapter to use the builtin port, since the output levels + available at the user port don't follow the RS232 standard. + +</descrip><p> + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Interrupts<p> + +The runtime for the Plus/4 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/smc.sgml b/doc/smc.sgml new file mode 100644 index 000000000..b58fc51ab --- /dev/null +++ b/doc/smc.sgml @@ -0,0 +1,596 @@ +<!doctype linuxdoc system> + +<article> +<title>ca65 Macros for Self Modifying Code +<author>Christian Krüger +<date>2012-02-19 + +<abstract> +The 'smc.inc' macro package for ca65 eases the use, increases the safeness and +self-explanation of 'self-modifying-code' (SMC). +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> +When reading assembler sources, self modifying code is often hard to identify +and applying it needs a lot of discipline. + +Since the cacheless 6502 is a thankful target of such kind of code, the macro +package will not only reduce this complexness, but also document the use. The +resulting source is more self-explanatory and so easier to maintain. + +While for general purposes SMC is not a desired form for implementations, it +can be quite useful for a small range of scenarios. Normally SMC will be +introduced when optimizing code in respect to: + +<itemize> +<item>speed and/or +<item>size. +</itemize> + +Please mind that SMC can only be applied for code in RAM, which means that a +general purpose library with SMC excludes ROM targets! + +The ca65 SMC macro package consists of two files: + +<itemize> +<item><tt>smc.inc</tt> +<item><tt>opcodes.inc</tt> +</itemize> + +The latter is only needed if you also plan to modify opcodes and not only data +within your code. + +<sect>Usage<p> +The use of the macros is quite simple: + +Original: + +<tscreen><verb> + PHA + JSR SUBROUTINE + PLA +</verb></tscreen> + +By applying SMC, the speed will now be increased by once cycle: + +SMC: + +<tscreen><verb> + SMC_StoreValue RestoreAccu + JSR SUBROUTINE +SMC RestoreAccu, { LDA #SMC_Value } +</verb></tscreen> + +The first line stores the value of the accu into the '<tt>RestoreAccu</tt>' +labeled SMC target. + +Please note: +<enum> +<item> for all SMC store or transfer operations, a second argument can be + given. This determines the register for the operation: + '<tt>SMC_StoreValue Label, y</tt>' will store the value of the + Y-register. + + If the second argument is missing, the accu will be used automatically. + +<item> The label targets a 'special SMC namespace'. It fits only to + destinations which are introduced with the macro '<tt>SMC</tt>'. A + normal label '<tt>RestoreAccu</tt>' wouldn't match and could even + coexist (even if you should abstain from doing so). + +<item> The macro '<tt>SMC_StoreValue</tt>' takes care, that the store + operation will occur on the value-position of a SMC-instruction. As + you will see, other macros influence other instruction part positions. + There is no consistency check, if the targeted SMC instruction acually + contains a value. Storing a 'value' on an immplied SMC instruction + would corrupt the following memory cell! +</enum> + +The second line needs no further explanation, this is just a placeholder for +some code in the example. + +The third line is the code line which is about to be modified. It has to start +with the '<tt>SMC</tt>' macro and must be labeled, so that the modification +can be designated. Then the unmodified code is given in curly braces. + +Please note the usage of the value placeholder 'SMC_Value'. Using such a +placeholder has two advantages: + +<enum> +<item> The code is better documented. It is clearly visible that the given + value is about to be changed. +<item> When examining an (initial) disassembly (e.g. in a debugger), these + placegolders can be better identified: They are fixed and, you may + notice that below, quite eye catching defined. +</enum> + +<sect1>Argument placeholders<p> + +There are four kinds of placeholders: + +<descrip> + + <label id="Address placeholder"> + <tag><tt>SMC_AbsAdr</tt></tag> + + Used to indicate an address. The value is '<tt>$FADE</tt>'. + + Example: <tt>STA SMC_AbsAdr</tt> + + + <label id="Zero-Page-Address placeholder"> + <tag><tt>SMC_ZpAdr</tt></tag> + + Used to indicate a zero-page-address. The value is '<tt>$00</tt>'. + + Example: <tt>LDA SMC_ZpAdr</tt> + + + <label id="Opcode placeholder"> + <tag><tt>SMC_Opcode</tt></tag> + + Used to indicate an instruction. The value is '<tt>NOP</tt>'. + + Example: <tt>SMC_Opcode</tt> + + + <label id="Immediate value placeholder"> + <tag><tt>SMC_Value</tt></tag> + + Used to indicate a value. The value is '<tt>$42</tt>'. + + Example: <tt>LDX #SMC_Value</tt> +</descrip> + +Attention: Often code is modified after the initial use - where using the +placeholders does not makes sense. Please mind also, that in very variable +expressions (e.g. opcode and argument is about to be changed), placeholders +can lead to unidentifyable code for a debugger/disassembler: + +<tt>SMC Example, { SMC_Opcode SMC_AbsAdr } </tt> + +Since the opcode is '<tt/NOP/', the value '<tt/$DE/' from '<tt/$FADE/' will +interpreted as opcode in a disassembler too. This breaks the correct +disassembly, because '<tt/$DE/' is interpreted as '<tt/DEC abx/'. Establishing +a valid placeholder instruction may be better: + +<tt>SMC Example, { sta SMC_AbsAdr } ; Note: Opcode will be modified too!</tt> + +<sect1>Accessing opcodes<p> + +Some macros are designed to access the instruction of a code line. To increase +readability, please use the opcodes as defined in the '<tt>opcodes.inc</tt>' +file. + +<descrip> + + <label id="Transfer opcode"> + <tag><tt>SMC_TransferOpcode label, opcode (, register)</tt></tag> + Loads and store an opcode to given SMC instruction. + + Example: + +<tscreen><verb> +SMC SumRegister, { LDA #10 } + JSR OUTPUT + SMC_TransferOpcode SumRegister, OPC_ADC_imm, x +</verb></tscreen> + +The macro above will load the opcode '<tt>ADC #</tt>' into the x - register +and stores it at the place of the '<tt>LDA #</tt>'. + + <label id="Load opcode"> + <tag><tt>SMC_LoadOpcode label (, register)</tt></tag> + Loads the opcode of a SMC line to the given register. + + Example: +<tscreen><verb> +SMC ShiftOrNothing, { LSL } + SMC_LoadOpcode ShiftOrNothing, y + CPY #OPC_NOP + BEQ Exit +</verb></tscreen> + + <label id="Store opcode"> + <tag><tt>SMC_StoreOpcode label (, register)</tt></tag> + Stores the value of the given register at the opcode place of a SMC line. + + Example: +<tscreen><verb> +SetBoldMode: + LDA #OPC_INX + SMC_StoreOpcode AdaptCharWidth + SMC_StoreOpcode AdaptUnderlineWidth + RTS + ... +SMC AdaptCharWidth, { NOP } + ... +SMC AdaptUnderlineWidth, { NOP } +</verb></tscreen> + +</descrip> + +<sect1>Accessing arguments<p> + +These marcos are determined to get, set and change arguments of instructions: + +<descrip> + + <label id="Change branch"> + <tag><tt>SMC_ChangeBranch label, destination (, register)</tt></tag> + + Used to modify the destination of a branch instruction. If the adress offset + exceeds the supported range of 8-bit of the 6502, a error will be thrown. + + Example: +<tscreen><verb> +Disable Handler: + SMC_ChangeBranch BranchToHandler, Exit + RTS + ... + LDA warning +SMC BranchToHandler, { BNE Handler } +Exit: + RTS +</verb></tscreen> + + + <label id="Transfer value"> + <tag><tt>SMC_TransferValue label, value (, register)</tt></tag> + + Changes the value of a SMC line. + + Example: +<tscreen><verb> +ClearDefault: + SMC_TransferValue LoadDefault, 0 + RTS + ... +SMC LoadDefault, { LDX #25 } +</verb></tscreen> + + + <label id="Load value"> + <tag><tt>SMC_LoadValue label (, register)</tt></tag> + + Retreives the value of a SMC line. + + Example: +<tscreen><verb> +ShowDefault: + SMC_LoadValue LoadDefault + JSR PrintValue + RTS + ... +SMC LoadDefault, { LDX #25 } +</verb></tscreen> + + + <label id="Store value"> + <tag><tt>SMC_StoreValue label (, register)</tt></tag> + + Stores the value in the register to given SMC line. + + Example: +<tscreen><verb> +InitCounters: + LDY #0 + SMC_StoreValue GetI, y + SMC_StoreValue GetJ, y + SMC_StoreValue GetK, y + ... +SMC GetI, { LDX #SMC_Value } + ... +SMC GetJ, { LDX #SMC_Value } + ... +SMC GetK, { LDX #SMC_Value } +</verb></tscreen> + + + <label id="Transfer low-byte"> + <tag><tt>SMC_TransferLowByte label, value (, register)</tt></tag> + + Does the same as '<tt>SMC_TransferValue</tt>' but should be used for + low-bytes of adresses for better readability. + + Example: +<tscreen><verb> +ActivateSecondDataSet: + SMC_TransferLowByte LoadData, $40 + RTS + ... +SMC LoadData, { LDA $2000 } +</verb></tscreen> + + + <label id="Load low-byte"> + <tag><tt>SMC_LoadLowByte label (, register)</tt></tag> + + Does the same as '<tt>SMC_LoadValue</tt>' but should be used for low-bytes + of adresses for better readability. + + Example: +<tscreen><verb> +IsSecondDataSetActive: + SMC_LoadLowByte LoadData, y + CPY #$40 + BNE NotActive + ... +SMC LoadData, { LDA $2000 } +</verb></tscreen> + + + <label id="Store low-byte"> + <tag><tt>SMC_StoreLowByte label (, register)</tt></tag> + + Does the same as '<tt>SMC_StoreValue</tt>' but should be used for low-bytes + of adresses for better readability. + + Example: +<tscreen><verb> +InitStructureBaseAddresses: + LDX #0 + SMC_StoreLowByte GetPlayerGraphic, x + SMC_StoreLowByte GetObjectGraphic, x + SMC_StoreLowByte StoreCollisionData, x + RTS + ... +SMC GetPlayerGraphic, { LDX $2000 } + ... +SMC GetObjectGraphic, { LDA $2100,x } + ... +SMC StoreCollisionData, { STY $2200 } +</verb></tscreen> + + + <label id="Transfer high-byte"> + <tag><tt>SMC_TransferHighByte label, value (, register)</tt></tag> + + Loads and stores the given value via the named register to the high-byte + adress portion of an SMC-instruction. + + Example: +<tscreen><verb> +PlaySFX: +SMC GetVolume { LDA $3200,x } + STA SoundOut + INX + BNE PlaySFX + ... +PlayOtherSound: + SMC_TransferHighByte GetVolume, $34 +</verb></tscreen> + + + <label id="Load high-byte"> + <tag><tt>SMC_LoadHighByte label (, register)</tt></tag> + + Loads the high-byte part of an SMC-instruction adress to the given register. + + Example: +<tscreen><verb> +PlaySFX: +SMC GetVolume { LDA $3200,x } + ... + SMC_LoadHighByte GetVolume + cmp #$34 + beq OtherSoundPlaying + ... +</verb></tscreen> + + + <label id="Store high-byte"> + <tag><tt>SMC_StoreHighByte label (, register)</tt></tag> + + Stores the high-byte adress part of an SMC-instruction from the given + register. + + Example: +<tscreen><verb> +SetupLevel2: + LDX #(>Level2Base) + SMC_StoreHighByte GetLevelData, x + SMC_StoreHighByte GetScreenData, x + SMC_StoreHighByte GetSoundData, x + RTS + ... +SMC GetLevelData, { LDA Level1Base+Data } + ... +SMC GetScreenData, { LDA Level1Base+Screen, x } + ... +SMC GetSoundData, { LDA Level1Base+Sound, y } +</verb></tscreen> + + + <label id="Transfer single adress"> + <tag><tt>SMC_TransferAddressSingle label, address (, register)</tt></tag> + + Transfers the contents of the given address via the given register to the + designated SMC instruction. + + Example: +<tscreen><verb> +PrintHello: + SMC_TransferAddressSingle GetChar, #HelloMsg + ... + LDX #0 +NextChar: +SMC GetChar, { LDA SMC_AbsAdr, x } + BEQ leave + JSR CharOut + INX + BNE NextChar +</verb></tscreen> + + + <label id="Transfer adress"> + <tag><tt>SMC_TransferAddress label, address</tt></tag> + + Loads contents of given address to A/X and stores the result to SMC + instruction. Allows reuse of register contents by using + '<tt>SMC_StoreAddress</tt>' for multiple SMC instruction modifications. + + Example: +<tscreen><verb> + SMC_TransferAddress JumpTo, #CloseChannel + ... +SMC JumpTo, { JMP OpenChannel } +</verb></tscreen> + + + <label id="Store address"> + <tag><tt>SMC_StoreAddress label</tt></tag> + + Stores the address value in a/x to a SMC instruction address position. + + Example: +<tscreen><verb> + SMC_StoreAddress GetData + ... +SMC GetData, { LDA SMC_AbsAdr } +</verb></tscreen> + +</descrip> + +<sect1>Operational macros<p> + +These marcos are determined to let read/modify/write opcodes work on parts of +SMC instructions. + +<descrip> + + <label id="Operate on value"> + <tag><tt>SMC_OperateOnValue opcode, label</tt></tag> + + Let given opcode work on the value part of a SMC instruction. + + Example: +<tscreen><verb> + SMC_OperateOnValue ASL, LoadMask ; shift mask to left + ... +SMC LoadMask, { LDA #$20 } +</verb></tscreen> + + <label id="Operate on low-byte"> + <tag><tt>SMC_OperateOnLowByte opcode, label</tt></tag> + + Same as '<tt/SMC_OperateOnValue/' but renamed for better readability when + accessing low-bytes of address. + + Example: +<tscreen><verb> + SMC_OperateOnLowByte DEC, AccessData + ... +SMC AccessData, { LDX Data } +</verb></tscreen> + + <label id="Operate on high-byte"> + <tag><tt>SMC_OperateOnHighByte opcode, label</tt></tag> + + Let the given opcode work on the high-byte part on a SMC-instruction. + + Example: +<tscreen><verb> +NextPage: + SMC_OperateOnHighByte INC, GetPageData + ... +SMC GetPageData, { LDA SourceData, X } +</verb></tscreen> +</descrip> + +<sect1>Scope macros<p> + +These marcos are determined to export and import SMC labels out of the current +file scope. Please handle with care! If you cannot abstain from leaving the +file scope, you should at least document the exported SMC lines very well. On +import side no checking is available if the SMC line is correct accessed (e.g. +invalid access to the value of an implied instruction)! + +<descrip> + <label id="Export SMC line under given name"> + <tag><tt>SMC_Export alias, label</tt></tag> + + SMC label will be exported under given alias. + + Example: +<tscreen><verb> +.proc GetValue +SMC LoadValue, { LDA #12 } + rts +.endproc + +SMC_Export GetValueLoader, GetValue::LoadValue +</verb></tscreen> + + <label id="Import SMC alias"> + <tag><tt>SMC_Import alias</tt></tag> + + SMC line is made accessible under given alias. + + Example: +<tscreen><verb> +SMC_Import GetValueLoader + ... + SMC_TransferValue GetValueLoader, #47 + ... +</verb></tscreen> +</descrip> + +<sect>A complex example<p> +Let's have a look on a quite sophisticated example for the usage of SMC. It +not only modifies code, but also the modification of the code is modified - +allowing reuse of some instructions. + +The code is from my 'memset()'implementation: + +<descrip> +<tscreen><verb> + 1: ... + 2: SMC_StoreAddress StoreAccuFirstSection + 3: + 4: StoreToFirstSection: + 5: SMC StoreAccuFirstSection, { sta SMC_AbsAdr, Y } + 6: ... + 7: RestoreCodeBranchBaseAdr: + 8: SMC FirstIncHighByte, { SMC_OperateOnHighByte inc, StoreAccuFirstSection } ; code will be overwritten to 'beq RestoreCode' (*) + 9: ... +10: SMC_TransferOpcode FirstIncHighByte, OPC_BEQ , x ; change code marked above with (*) +11: SMC_TransferValue FirstIncHighByte, #(restoreCode - RestoreCodeBranchBaseAdr-2), x ; set relative adress to 'RestoreCode' +12: ... +13: restoreCode: +14: SMC_TransferOpcode FirstIncHighByte, OPC_INC_abs , x ; restore original code... +15: SMC_TransferValue FirstIncHighByte, #(<(StoreToFirstSection+2)), x ; (second byte of inc contained low-byte of adress) +16: ... +</verb></tscreen> + +Some explanation: + +Line 2: The register pair A/X contains an address, which is stored on the +address location of a SMC line called 'StoreAccuFirstSection'. According to +cc65's calling convention, the low-byte is in accu while the high-byte is in +the X-register. + +Line 5: The (modified) address is accessed. + +Line 8: We have a line here, which is about to be modified (it begins with +SMC), but itself modifies code. Please note: Contrary to the rest of SMC-line +modifying macros, the 'OperateOn'-macros just expand their given arguments +into a single instruction line. These can be changed of course too. + +Line 10,11: These lines construct a branch operation for line 8: The +X-register will be used to change it from 'inc StoreAccuFirstSection+2' +(high-byte operation) to 'beq restoreCode'. Please note: To calculate the +relaive branch offset, we introduced a second label +('RestoreCodeBranchBaseAdr') for to calculate it. Some could also use the +internal name of the SMC label, but you should abstain to do so - it may be +changed in the future... + +Line 14,15: The original code from line 8 is reestablished. +</descrip> +</article> + diff --git a/doc/sp65.sgml b/doc/sp65.sgml new file mode 100644 index 000000000..32dead645 --- /dev/null +++ b/doc/sp65.sgml @@ -0,0 +1,424 @@ +<!doctype linuxdoc system> <!-- -*- text-mode -*- --> + +<article> +<title>sp65 Users Guide +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>2012-03-11 + +<abstract> +sp65 is a sprite and bitmap utility that is part of the cc65 development suite. +It is used to convert graphics and bitmaps into the target formats of the +supported machines. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +sp65 is a tool that converts images from common formats into formats used +on the 6502 platforms that are the targets of the cc65 compiler suite. In +addition, it allows some very simple operation with loaded graphics data, like +using part of an image for further processing. + +The utility has been designed in a way that adding additional source or target +formats is easy. The final output is either binary, or C/assembler source. + + + +<sect>Usage<p> + + +<sect1>Command line option overview<p> + +The sp65 utility accepts the following options: + +<tscreen><verb> +--------------------------------------------------------------------------- +Usage: sp65 [options] file [options] [file] +Short options: + -V Print the version number and exit + -c fmt[,attrlist] Convert into target format + -h Help (this text) + -lc List all possible conversions + -r file[,attrlist] Read an input file + -v Increase verbosity + -w file[,attrlist] Write the output to a file + +Long options: + --convert-to fmt[,attrlist] Convert into target format + --help Help (this text) + --list-conversions List all possible conversions + --pop Restore the original loaded image + --read file[,attrlist] Read an input file + --slice x,y,w,h Generate a slice from the loaded bitmap + --verbose Increase verbosity + --version Print the version number and exit + --write file[,attrlist] Write the output to a file +--------------------------------------------------------------------------- +</verb></tscreen> + + +<sect1>Command line options in detail<p> + +Below is a description of all the command line options. For the concept of +attribute lists see <ref id="attr-lists" name="below">. + +<descrip> + + <label id="option--convert-to"> + <tag><tt>-c, --convert-to format[,attrlist]</tt></tag> + + Convert a bitmap into one of the supported target formats. The option + argument must at least contain the "format" attribute. For more attributes, + see section <ref id="conversions" name="Conversions">. + + + <label id="option--help"> + <tag><tt>-h, --help</tt></tag> + + Print the short option summary shown above. + + + <label id="option--list-conversions"> + <tag><tt>-lc, --list-conversions</tt></tag> + + Print a list of possible conversions. + + + <label id="option--pop"> + <tag><tt>--pop</tt></tag> + + Restore the working copy of the bitmap from the one originally loaded from + the file. This may for example be used when creating several output files + from one input file. + + + <label id="option--read"> + <tag><tt>-r, --read filename[,attrlist]</tt></tag> + + Read an input file. The option argument must at least contain the "name" + attribute. See <ref id="input-formats" name="input formats"> for more + information. + + + <label id="option-v"> + <tag><tt>-v, --verbose</tt></tag> + + Increase verbosity. Usually only needed for debugging purposes. You may use + this option more than one time for even more verbose output. + + + <label id="option-V"> + <tag><tt>-V, --version</tt></tag> + + Print the version number of the assembler. If you send any suggestions or + bugfixes, please include the version number. + + + <label id="option--write"> + <tag><tt>-w, --write filename[,attrlist]</tt></tag> + + Write an output file. The option argument must at least contain the "name" + attribute. See <ref id="output-formats" name="output formats"> for more + information. + +</descrip> +<p> + + + +<sect>Processing pipeline<label id="processing-pipeline"><p> + +sp65 consists of + +<itemize> +<item>Front ends that read graphics data, +<item>processors for graphics data, +<item>converters +<item>and output modules for several formats. +</itemize> + +These modules can be combined to a pipeline that reads data, does some +optional bitmap processing, converts the bitmap into a target format, and +writes this binary data to disk in one of several forms. + + + +<sect>Attribute lists<label id="attr-lists"><p> + +As described in <ref id="processing-pipeline" name="Processing pipeline">, +sp65 consists of lots of different modules that may be combined in different +ways, to convert an input bitmap to some output. + +Many of the processors and converters have options to change the way, they're +working. To avoid having lots of command line options that must be parsed on +high level and passed down to the relevant parts of the program, sp65 features +something called "attribute lists". Attribute lists are lists of +attribute/value pairs. These lists are parsed by the main program module +without any knowledge about their meaning. Lower level parts just grab the +attributes they need. + +In general, attribute lists look like this: + +<tscreen><verb> + attr1=val1[,attr2=val2[,...]] +</verb></tscreen> + +Instead of the comma, colons may also be used (even mixed). + +To simplify things and to make the most common options look "normal", some +mandatory attributes may be given without an attribute name. If the attribute +name is missing, the default name is determined by the position. For example, +the option <tt/<ref id="option--read" name="--read">/ does always need a file +name. The attribute name for the file name is "name". To avoid having to type + +<tscreen><verb> + sp65 --read name=ball.pcx ... +</verb></tscreen> + +the first attribute gets the default name "name" assigned. So if the first +attribute doesn't have a name, it is assumed that it is the file name. This +means that instead of the line above, one can also use + +<tscreen><verb> + sp65 --read ball.pcx ... +</verb></tscreen> + +The second attribute for <tt/--read/ is the format of the input file. So when +using + +<tscreen><verb> + sp65 --read ball.pic:pcx ... +</verb></tscreen> + +a PCX file named "ball.pic" is read. The long form would be + +<tscreen><verb> + sp65 --read name=ball.pic:format=pcx ... +</verb></tscreen> + +Changing the order of the attributes is possible only when explicitly +specifying the names of the attributes. Using + +<tscreen><verb> + sp65 --read pcx:ball.pic ... +</verb></tscreen> + +will make sp65 complain, because it tries to read a file named "pcx" with an +(unknown) format of "ball.pic". The following however will work: + +<tscreen><verb> + sp65 --read format=pcx:name=ball.pic ... +</verb></tscreen> + +The attributes that are valid for each processor or converter are listed +below. + + + +<sect>Input formats<label id="input-formats"><p> + +Input formats are either specified explicitly when using <tt/<ref +id="option--read" name="--read">/, or are determined by looking at the +extension of the file name given. + +<sect1>PCX<p> + +While sp65 is prepared for more, this is currently the only possible input +format. There are no additional attributes for this format. + + + +<sect>Conversions<label id="conversions"><p> + +<sect1>GEOS bitmap<p> + +The current bitmap working copy is converted to a GEOS compacted bitmap. This +format is used by several GEOS functions (i.e. 'BitmapUp') and is described +in 'The Official GEOS Programmers Reference Guide', chapter 4, section +'Bit-Mapped Graphics'. + + +<sect1>GEOS icon<p> + +The current bitmap working copy is converted to GEOS icon format. A GEOS icon +has the same format as a C64 high resolution sprite (24x21, monochrome, 63 +bytes). There are no additional attributes for this conversion. + + +<sect1>Koala image<p> + + +<sect1>Lynx sprite<p> + +Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size +of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by +102 pixels which makes very large sprites useless. + +The number per pixels is taken from the number of colors of the input bitmap. + +There are a few attributes that you can give to the conversion software. + +<descrip> + + <tag/mode/ + The first is what kind of encoding to use for the sprite. The attribute for + this is called "mode" and the possible values are "literal", "packed" or + "transparent". The default is "packed" if no mode is specified. + + The "literal" is a totally literal mode with no packing. In this mode the + number of pixels per scanline will be a multiple of 8 both right and left from + the action point. + + If the source bitmap edge ends with a color where the least significant bit is + one then there will be an extra 8 zero bits on that scan line. + + So if you are using totally literal sprites and intend to change them at + runtime then please add a single pixel border far left and far right with + zeros in order to prevent graphical glitches in the game. + + The standard encoding is called "packed". In this mode the sprite is packed + using run-length encoding and literal coding mixed for optimisation to + produce a small sprite. + + The last encoding mode "transparent" is like packed. But here we know that + the index 0 will be transparent so we can clip off all 0 pixels from the left + and right edge of the sprite. This will produce the smallest sprite possible + on the Lynx. The sprite is not rectangular anymore. + + <tag/ax/ + The sprite is painted around the Anchor point. The anchor point x can be + between 0 and the width of the sprite - 1. If anchor point x is zero then + painting the sprite in location 10,20 will set the left edge of the sprite + 10 pixels from the left of the Lynx screen. When the sprite is scaled by + hardware the anchor point stays in place and the sprite grows or shrinks + around the anchor point. The default value is 0 (left). + + <tag/ay/ + The sprite is painted around the Anchor point. The anchor point y can be + between 0 and the height of the sprite - 1. If anchor point y is zero then + painting the sprite in location 10,20 will set the top of the sprite 20 + pixels from the top of the Lynx screen. When the sprite is scaled by + hardware the anchor point stays in place and the sprite grows or shrinks + around the anchor point. The default value is 0 (top). + +</descrip> + +<sect1>VIC2 sprite<p> + + + + +<sect>Output formats<label id="output-formats"><p> + +Using <tt/<ref id="option--write" name="--write">/ it is possible to write +processed data to an output file. An attribute "name" is mandatory, it is used +as the file name for the output. The output format can be specified using an +attribute named "format". If this attribute doesn't exist, the output format +is determined by looking at the file name extension. + + +<sect1>Binary<p> + +For this format, the processed data is written to the output file in raw +binary format. There are no additional attributes (besides "name" and +"format") for this output format. + + +<sect1>Assembler code<p> + +For this format, the processed data is written to the output file in ca65 +assembler format. There are several attributes for this output format: + +<descrip> + + <tag/base/ + The value for this attribute specifies the numeric base for the data + values. It may be either 2, 10 or 16. The default is 16. If the base is + 2, the numbers are prefixed by '%', if the base is 16, the numbers are + prefixed by '$'. For base 10, there is no prefix. + + <tag/bytesperline/ + The value for this attribute specifies the number of bytes output in one + line of the assembler file. The default is 16. + + <tag/ident/ + This is an optional attribute. When given, the output processor will wrap + the data into a <tt/.PROC/ with the given name. In addition, three constants + are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/ + and <tt/HEIGHT/. + +</descrip> + + + +<sect1>C code<p> + +When using C output format, a small piece of C source code is generated that +defines the data containing the output in an array of <tt/unsigned char/. + +Possible attributes for this format are: + +<descrip> + <tag/base/ + The value for this attribute specifies the numeric base for the data values. + It may be either 10 or 16. The default is 16. If the base is 16, the numbers + are prefixed by 0x. For base 10, there is no prefix. + + <tag/bytesperline/ + The value for this attribute specifies the number of bytes output in one + line of the C source code. The default is 16. + + <tag/ident/ + This is an optional attribute. When given, the output processor will wrap + the data into an array of unsigned char with the given name. In addition, + three <tt/#define/s are added for <tt/<ident>_COLORS/, + <tt/<ident>_WIDTH/ and <tt/<ident>_HEIGHT/. + +</descrip> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the assembler, if you find any bugs, or if +you're doing something interesting with the assembler, I would be glad to +hear from you. Feel free to contact me by email +(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">). + + + +<sect>Copyright<p> + +sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz +and others. For usage of the binaries and/or sources the following conditions +do apply: + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + + + +</article> + + + diff --git a/doc/supervision.sgml b/doc/supervision.sgml new file mode 100644 index 000000000..504ba5194 --- /dev/null +++ b/doc/supervision.sgml @@ -0,0 +1,179 @@ +<!doctype linuxdoc system> + +<article> + +<title>Watara Supervision specific information for cc65 +<author>Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2005-07-17 + +<abstract> +An overview over the Supervision runtime system as it is implemented for the +cc65 C compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the Supervision runtime system as it comes +with the cc65 C compiler. It describes the memory layout, Supervision specific header +files, available drivers, and any pitfalls specific to that platform. + +Please note that Supervision specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the Supervision target +is a 2×16 kbyte machine language program. It is of course +possible to change this behaviour by using one of the different linker configs. + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with the I/O area enabled, +which gives a usable memory range of $8000 - $FFF9. +More ROM may need additional bankswitching code. + +Special locations: + +<descrip> + <tag/Text screen/ +<!-- The text screen is located at VRAM $4000.--> + No conio support is currently available for the Supervision. + + <tag/Stack/ + The C runtime stack is located at $1FFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing Supervision specific code may use the <tt/supervision.h/ header file. + + +<sect1>Supervision specific functions<p> + +<itemize> +<item>waitvblank +</itemize> + + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/supervision.inc/ include file do +allow access to hardware located in the address space. + +<descrip> + + <tag><tt/IO/</tag> + The <tt/IO/ defines allow access to the IO chip. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the Supervision. +<!--A TGI driver for the standard graphics mode (160×160 in 4 colors) is +available, but must be statically linked, because no file I/O is available. +See the documentation for the <htmlurl url="co65.html" name="co65 utility"> +for information on how to do that.--> + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the Supervision. + + +<sect1>Joystick drivers<p> + +No joystick drivers are currently available for the Supervision. +<!--A joystick driver for the standard buttons is available, but must be +statically linked, because no file I/O is available. See the documentation for +the <htmlurl url="co65.html" name="co65 utility"> for information on how to do +that.--> + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the Supervision. + + +<sect1>RS232 device drivers<p> + +No communication port drivers are currently available for the Supervision. + + + +<sect>Limitations<p> + +<sect1>Disk I/O<p> + +The existing library for the Supervision doesn't implement C file +I/O. There are even no hacks for the <tt/read()/ and <tt/write()/ routines. + +To be more concrete, this limitation means that you cannot use any of the +following functions (and a few others): + +<itemize> +<item>fclose +<item>fopen +<item>fread +<item>fprintf +<item>fputc +<item>fscanf +<item>fwrite +<item>... +</itemize> + + + +<sect>Other hints<p> + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article> diff --git a/doc/using-make.sgml b/doc/using-make.sgml new file mode 100644 index 000000000..5affe3b9f --- /dev/null +++ b/doc/using-make.sgml @@ -0,0 +1,156 @@ +<!doctype linuxdoc system> + +<article> + +<title>Using GNU Make with cc65 +<author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> +<date>2009-06-26 + +<abstract> +How to build your program using the GNU Make utility. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This document describes how to build your programs using the cc65 development +tools and the GNU Make utility. + +The cc65 development package doesn't come with a make utility. However this is +no issue because GNU Make works very nicely with cc65. + + + +<sect>What is GNU Make?<p> + +GNU Make is a both very powerful and very popular make utility. It might even +be called the de facto standard for make utilities. For more information see +the GNU Make home page: + +<url url="http://www.gnu.org/software/make/"> + +The cc65 development package is available as binaries for several host systems +and can easily built for quite some additional systems. The very same is true +for GNU Make so a cc65-based project coming with a GNU Make Makefile can easily +be built by any cc65 developer no matter what host system is used. + +Because of the strong alignment of the cc65 compiler with the ISO C standard it +is very well feasible to compile a single C code base both with the cc65 +compiler and other C compilers like for example GCC. GNU Make turns out to be +very well suited to build projects for several target systems using multiple +compilers as it isn't tied to any C compiler. + + + +<sect>A sample Makefile<p> + +This Makefile is a fully functional sample for compiling several C sources +(here <tt/foo.c/ and <tt/bar.c/) and link the resulting object files into an +executable program (here <tt/foobar/): + +<tscreen><verb> +SOURCES = foo.c bar.c + +PROGRAM = foobar + +ifdef CC65_TARGET +CC = $(CC65_HOME)/bin/cl65 +CFLAGS = -t $(CC65_TARGET) --create-dep $(<:.c=.d) -O +LDFLAGS = -t $(CC65_TARGET) -m $(PROGRAM).map +else +CC = gcc +CFLAGS = -MMD -MP -O +LDFLAGS = -Wl,-Map,$(PROGRAM).map +endif + +######################################## + +.SUFFIXES: +.PHONY: all clean +all: $(PROGRAM) + +ifneq ($(MAKECMDGOALS),clean) +-include $(SOURCES:.c=.d) +endif + +%.o: %.c + $(CC) -c $(CFLAGS) -o $@ $< + +$(PROGRAM): $(SOURCES:.c=.o) + $(CC) $(LDFLAGS) -o $@ $^ + +clean: + $(RM) $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map +</verb></tscreen> + +<bf/Important:/ When using the sample Makefile above via copy & paste it is +necessary to replace the eight spaces at the beginning of command lines (lines +26, 29 and 32) with a tab character (ASCII code 9). + + +<sect1>Invoking the sample Makefile<p> + +Without any specific configuration the sample Makefile will compile and link +using GCC. In order to rather use cc65 the variable <tt/CC65_TARGET/ needs to be +defined. This may by done as an environment variable or simply as part of the +Makefile. However to quickly switch between compilers and/or cc65 targets it is +best done on the GNU Make command line like this: + +<tscreen><verb> +make CC65_TARGET=c64 +</verb></tscreen> + +The sample Makefile presumes the variable <tt/CC65_HOME/ to point to the +directory cc65 is located in. Again there are several ways to define this +variable but as its value typically won't change often it is best done as an +environment variable. On Windows the cc65 .exe installer package takes care +of creating a <tt/CC65_HOME/ environment variable. + + +<sect1>Understanding the sample Makefile<p> + +Most parts of the sample Makefile follow the guidelines in the +<htmlurl url="http://www.gnu.org/software/make/manual/make.html" name="GNU Make Manual"> +that can be searched online for background information. The automatic generation of +dependency however rather works as described by the GNU Make maintainer Paul D. Smith in +<htmlurl url="http://make.paulandlesley.org/autodep.html#advanced" name="Advanced Auto-Dependencies">. +Fortunately both GCC and cc65 directly support this method in the meantime. + + +<sect1>Invoking the sample Makefile on Windows<p> + +The recommended way to use GNU Make on Windows is to install it as part of a +Cygwin environment. For more information see the Cygwin home page: + +<url url="http://www.cygwin.com/"> + +If however installing Cygwin shouldn't be an option for one or the other reason +then the sample Makefile may be invoked from the Windows Command Prompt (cmd.exe) +by downloading the following programs: + +<itemize> +<item>make.exe: <url url="http://gnuwin32.sourceforge.net/packages/make.htm"> +<item>rm.exe: <url url="http://gnuwin32.sourceforge.net/packages/coreutils.htm"> +</itemize> + + + +<sect>Target-specific Variable Values<p> + +The very limited resources of the cc65 target machines now and then require +manual optimization of the build process by compiling individual source files +with different compiler options. GNU Make offers +<htmlurl url="http://www.gnu.org/software/make/manual/html_node/Target_002dspecific.html" name="Target-specific Variable Values"> +perfectly suited for doing so. For example placing the code of the two modules +<tt/foo/ and <tt/bar/ in the segment <tt/FOOBAR/ can be archived with this +target-specific variable definition: + +<tscreen><verb> +foo.o bar.o: CFLAGS += --code-name FOOBAR +</verb></tscreen> + +</article> diff --git a/doc/vic20.sgml b/doc/vic20.sgml new file mode 100644 index 000000000..1227ee667 --- /dev/null +++ b/doc/vic20.sgml @@ -0,0 +1,269 @@ +<!doctype linuxdoc system> + +<article> + +<title>Commodore VIC20 (aka VC20) specific information for cc65 +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +Stefan A. Haubenthal, <htmlurl url="mailto:polluks@sdf.lonestar.org" name="polluks@sdf.lonestar.org"> +<date>2004-09-13 + +<abstract> +An overview over the VIC20 runtime system as it is implemented for the cc65 C +compiler. +</abstract> + +<!-- Table of contents --> +<toc> + +<!-- Begin the document --> + +<sect>Overview<p> + +This file contains an overview of the VIC20 runtime system as it comes with the +cc65 C compiler. It describes the memory layout, VIC20 specific header files, +available drivers, and any pitfalls specific to that platform. + +Please note that VIC20 specific functions are just mentioned here, they are +described in detail in the separate <htmlurl url="funcref.html" name="function +reference">. Even functions marked as "platform dependent" may be available on +more than one platform. Please see the function reference for more +information. + + +<sect>Binary format<p> + +The standard binary output format generated by the linker for the VIC20 target +is a machine language program with a one line BASIC stub, which calls the +machine language part via SYS. This means that a program can be loaded as +BASIC program and started with RUN. It is of course possible to change this +behaviour by using a modified startup file and linker config. + + +<sect>Memory layout<p> + +cc65 generated programs with the default setup run with unexpanded memory +(RAM at $A000 - $BFFF may be used for the heap), +which gives a usable memory range of $1000 - $1DFF. +All ROM entry points may be called directly without additional code. + +Special locations: + +<descrip> + <tag/Text screen/ + The text screen is located at $1E00 (as in the standard setup). + + <tag/Stack/ + The C runtime stack is located at $1DFF and growing downwards. + + <tag/Heap/ + The C heap is located at the end of the program and grows towards the C + runtime stack. + +</descrip><p> + + + +<sect>Platform specific header files<p> + +Programs containing VIC20 specific code may use the <tt/vic20.h/ or <tt/cbm.h/ +header files. Using the later may be an option when writing code for more than +one CBM platform, since it includes <tt/vic20.h/ and declares several functions +common to all CBM platforms. + + +<sect1>VIC20 specific functions<p> + +There are currently no special VIC20 functions. + + + +<sect1>CBM specific functions<p> + +Some functions are available for all (or at least most) of the Commodore +machines. See the <htmlurl url="funcref.html" name="function reference"> for +declaration and usage. + +<itemize> +<item>cbm_close +<item>cbm_closedir +<item>cbm_k_setlfs +<item>cbm_k_setnam +<item>cbm_k_load +<item>cbm_k_save +<item>cbm_k_open +<item>cbm_k_close +<item>cbm_k_readst +<item>cbm_k_chkin +<item>cbm_k_ckout +<item>cbm_k_basin +<item>cbm_k_bsout +<item>cbm_k_clrch +<item>cbm_load +<item>cbm_open +<item>cbm_opendir +<item>cbm_read +<item>cbm_readdir +<item>cbm_save +<item>cbm_write +<item>get_tv +</itemize> + + +<sect1>Hardware access<p> + +The following pseudo variables declared in the <tt/vic20.h/ header file do allow +access to hardware located in the address space. Some variables are +structures, accessing the struct fields will access the chip registers. + +<descrip> + + <tag><tt/VIC/</tag> + The <tt/VIC/ structure allows access to the VIC (the graphics + controller). See the <tt/_vic.h/ header file located in the include + directory for the declaration of the structure. + + <tag><tt/VIA1, VIA2/</tag> + Access to the two VIA (versatile interface adapter) chips is available via + the <tt/VIA1/ and <tt/VIA2/ variables. The structure behind these variables + is explained in <tt/_6522.h/. + + <tag><tt/COLOR_RAM/</tag> + A character array that mirrors the color RAM of the VIC20 at $9600. + +</descrip><p> + + + +<sect>Loadable drivers<p> + +The names in the parentheses denote the symbols to be used for static linking of the drivers. + + +<sect1>Graphics drivers<p> + +No graphics drivers are currently available for the VIC20. + + +<sect1>Extended memory drivers<p> + +No extended memory drivers are currently available for the VIC20. + + +<sect1>Joystick drivers<p> + +<descrip> + + <tag><tt/vic20-stdjoy.joy (vic20_stdjoy)/</tag> + Supports one standard joystick connected to the joysticks port of the VIC20. + + <tag><tt/vic20-ptvjoy.joy (vic20_ptvjoy)/</tag> + Driver for the Protovision 4-player adapter contributed by Groepaz. See + <htmlurl url="http://www.protovision-online.de/hardw/hardwstart.htm" + name="http://www.protovision-online.de/hardw/hardwstart.htm"> for prices and + building instructions. Up to three joysticks are supported. + +</descrip><p> + + +<sect1>Mouse drivers<p> + +No mouse drivers are currently available for the VIC20. + + +<sect1>RS232 device drivers<p> + +No VIC1011 drivers are currently available for the VIC20. + + + +<sect>Limitations<p> + + + +<sect>Other hints<p> + +<sect1>Escape code<p> + +For an Esc press CTRL and [ key. + +<sect1>Passing arguments to the program<p> + +Command line arguments can be passed to <tt/main()/. Since this is not +supported by BASIC, the following syntax was chosen: + +<tscreen><verb> + RUN:REM ARG1 " ARG2 IS QUOTED" ARG3 "" ARG5 +</verb></tscreen> + +<enum> +<item>Arguments are separated by spaces. +<item>Arguments may be quoted. +<item>Leading and trailing spaces around an argument are ignored. Spaces within + a quoted argument are allowed. +<item>The first argument passed to <tt/main/ is the program name. +<item>A maximum number of 10 arguments (including the program name) are + supported. +</enum> + + +<sect1>Program return code<p> + +The program return code (low byte) is passed back to BASIC by use of the +<tt/ST/ variable. + + +<sect1>Using extended memory<p> + +The extended memory at $A000 may be added to the heap by using the following +code: + +<tscreen><verb> + /* Check for the existence of RAM */ + if (PEEK(0xA000) == POKE(0xA000, PEEK(0xA000)+1)) {<br> + /* Add it to the heap */ + _heapadd ((void *) 0xA000, 0x2000); + } +</verb></tscreen> + + +<sect1>Interrupts<p> + +The runtime for the VIC20 uses routines marked as <tt/.INTERRUPTOR/ for +interrupt handlers. Such routines must be written as simple machine language +subroutines and will be called automatically by the interrupt handler code +when they are linked into a program. See the discussion of the <tt/.CONDES/ +feature in the <htmlurl url="ca65.html" name="assembler manual">. + + + +<sect>Bugs/Feedback<p> + +If you have problems using the library, if you find any bugs, or if you're +doing something interesting with it, I would be glad to hear from you. Feel +free to contact me by email (<htmlurl url="mailto:uz@cc65.org" +name="uz@cc65.org">). + + + +<sect>License<p> + +This software is provided 'as-is', without any expressed or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. + +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: + +<enum> +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. +</enum> + +</article>