the10thwiz/cc65
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'master' into feature/plus4-tgi-driver

Browse Source
This commit is contained in:
Bob Andrews
2025-06-01 23:12:27 +02:00
committed by GitHub
parent 0402fbd4b8 0122307399
commit aa4a791cc3
2213 changed files with 191473 additions and 27985 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/Makefile
View File

@@ -46,7 +46,6 @@ clean:
$(RM) -r ../html ../info
install:
$(if $(PREFIX),,$(error variable "PREFIX" must be set))
ifeq ($(wildcard ../html),../html)
$(INSTALL) -d $(DESTDIR)$(htmldir)
$(INSTALL) -m0644 ../html/*.* $(DESTDIR)$(htmldir)

151
doc/apple2.sgml
View File

@@ -33,7 +33,7 @@ more information.
The standard binary file format generated by the linker for the
Apple&nbsp;&rsqb;&lsqb; target is an <url name="AppleSingle"
url="http://kaiser-edv.de/documents/AppleSingle_AppleDouble.pdf"> file.
url="https://nulib.com/library/AppleSingle_AppleDouble.pdf"> file.
The default load address is &dollar;803.
<bf/AppleCommander 1.4.0/ or later (available at <url
@@ -62,7 +62,7 @@ Special locations:
</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.
However while running module constructors 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
@@ -73,7 +73,7 @@ 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 <ref id="link-configs" name="linker configuration"> parameters. There are
several usefull settings:
several useful settings:
<descrip>
@@ -92,7 +92,28 @@ several usefull settings:
</descrip><p>
<descrip>
<tag/Installing your code in the Language Card/
The code in the LC segment will automatically be copied from the end of the
binary into the Language Card at startup, even if the segment is empty (a
0-byte copy). This allows for tighter code. This code will be copied using the
Applesoft BLTU2 function that is available starting with the Apple ][+,
but not in the original Apple ][ with an Integer BASIC ROM. This shows as
a "RANGE ERROR. STOPPING AT ..." message on startup.
If you want to target the Integer BASIC original Apple ][, you can link in an
alternative implementation of the LC segment loading, at the cost of linking
in memcpy (60 bytes):
Using <tt/apple2-integer-basic-compat.o/ is as simple as placing it on the linker
command line like this:
<tscreen><verb>
cl65 -t apple2 myprog.c apple2-integer-basic-compat.o
</verb></tscreen>
</descrip>
<sect>Linker configurations<label id="link-configs"><p>
@@ -281,7 +302,7 @@ AppleCommander option to put LOADER.SYSTEM on a ProDOS 8 disk image is <tt/-p/.
If the cc65 program can be successfully linked as system program using the linker
configuration <ref id="apple-sys-cfg" name="apple2-system.cfg">, but
uses the heap either explicitly or implicitly (i.e. by loading a driver) then
the memory from &dollar;800 to &dollar;2000 can be added to the heap by calling
the memory from &dollar;800 to &dollar;1FFF can be added to the heap by calling
<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/.
@@ -289,9 +310,9 @@ the memory from &dollar;800 to &dollar;2000 can be added to the heap by calling
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.
<url url="funcref.html#posix_memalign" name="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 &dollar;800 and
@@ -321,18 +342,40 @@ Programs containing Apple&nbsp;&rsqb;&lsqb; specific code may use the
<sect1>Apple&nbsp;&rsqb;&lsqb; specific functions<p>
The functions listed below are special for the Apple&nbsp;&rsqb;&lsqb;. See
the <url url="funcref.html" name="function reference"> for declaration and
The functions and variables listed below are special for the Apple&nbsp;&rsqb;&lsqb;.
See the <url url="funcref.html" name="function reference"> for declaration and
usage.
<itemize>
<item>_auxtype
<item>_dos_type
<item>_filetype
<item>_datetime
<item>allow_lowercase
<item>beep
<item>dir_entry_count
<item>get_tv
<item>get_ostype
<item>gmtime_dt
<item>mktime_dt
<item>rebootafterexit
<item>ser_apple2_slot
<item>tgi_apple2_mix
<item>videomode
</itemize>
<sect1>Apple IIgs specific functions in accelerator.h<p>
In addition to those, the <tt/accelerator.h/ header file contains three functions
to help determine whether the program is running on a IIgs, and change the IIgs
CPU speed. See the <url url="funcref.html" name="function reference"> for declaration and
usage.
<itemize>
<item>detect_iigs
<item>get_iigs_speed
<item>set_iigs_speed
</itemize>
@@ -364,13 +407,17 @@ The names in the parentheses denote the symbols to be used for static linking of
with <tt/-S $4000/ to reserve the first hires page or with <tt/-S $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 &dollar;803 to &dollar;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
doesn't use the heap explicitly because loading the driver (and in fact
already opening the driver file) uses the heap implicitly.
</descrip><p>
@@ -427,17 +474,47 @@ The names in the parentheses denote the symbols to be used for static linking of
<descrip>
<tag><tt/a2.ssc.ser (a2_ssc_ser)/</tag>
Driver for the Apple&nbsp;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
Driver for the Apple&nbsp;II Super Serial Card.
The SSC is an extension card for the II, II+, IIe; the Apple //c and //c+ have
the same hardware and firmware integrated.
It supports up to 9600 baud, supports no flow control and hardware flow control
(RTS/CTS) and does interrupt driven receives. Speeds faster than 9600 baud
aren't reachable because the ROM and ProDOS IRQ handlers are too slow.
Software flow control (XON/XOFF) is not supported.
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.
Note that using the driver at SER_BAUD_115200 will disable IRQs. It will be up
to the users to use the serial port, either by re-enabling IRQs themselves,
or by directly poll-reading the ACIA DATA register without the help of ser_get().
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&nbsp;II slots, but <tt/ser_open()/ fails with
<tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
In the Apple //c and //c+, slot 1 is the printer port, and slot 2 is the modem
port.
Never call <tt/ser_apple2_slot()/ after <tt/ser_open()/.
<tag><tt/a2.gs.ser (a2_gs_ser)/</tag>
Driver for the Apple&nbsp;IIgs serial ports (printer and modem).
It supports up to 9600 baud, supports no flow control and hardware flow control
(RTS/CTS) and does interrupt driven receives. Speeds faster than 9600 baud
aren't reachable because the ROM and ProDOS IRQ handlers are too slow.
Software flow control (XON/XOFF) is not supported.
Note that transmits are not interrupt driven, and the transceiver blocks if
the receiver asserts flow control because of a full buffer.
The driver defaults to opening the modem port. Calling <tt/ser_apple2_slot()/
prior to <tt/ser_open()/ allows to select the printer port (1) or the modem
port (0).
Never call <tt/ser_apple2_slot()/ after <tt/ser_open()/.
</descrip><p>
@@ -544,6 +621,28 @@ program. See the discussion of the <tt/.CONDES/ feature in the <url
url="ca65.html" name="assembler manual">.
<sect1>ProDOS date/time manipulation<p>
<descrip>
The readdir and stat function return ProDOS timestamps in their file
creation/modification time attributes. You can convert them to more portable
time representations using either:
<tag/struct tm/
<tt/struct tm* __fastcall__ gmtime_dt (const struct datetime* dt);/
Converts a <tt/struct datetime/ into a <tt/struct tm/. Returns NULL in case
of error and sets errno.
<tag/time_t/
<tt/time_t __fastcall__ mktime_dt (const struct datetime* dt);/
Parses a <tt/struct datetime/ and returns a UNIX timestamp. Returns 0 on error and
sets errno.
</descrip>
<sect1>DIO<p>
<descrip>
@@ -575,15 +674,13 @@ url="ca65.html" name="assembler manual">.
<tag>Explanation of File Types</tag>
ProDOS associates a file type and an auxiliary type with each file.
ProDOS 8 associates a file type and an auxiliary type with each file.
These type specifications are separate from the file's name, unlike
Windows which uses the file name's suffix (a.k.a.
extension) to specify the file type. For example, <tt/.exe/,
<tt/.doc/, or <tt/.bat/.
The ProDOS low-level
Machine-Language Interface (MLI) functions for creating and opening
files require these types to be specified. And if they don't match
with the file being opened, the operation may fail.
The ProDOS 8 Machine-Language Interface (MLI) function for creating a
file require these types to be specified.
In contrast, the ISO C function <tt/fopen()/ and the POSIX function
<tt/open()/ have no parameter to specify either a file type or an
@@ -605,9 +702,17 @@ url="ca65.html" name="assembler manual">.
The header file <tt/apple2_filetype.h/ also defines many values
that can be used to set these variables. It is included in
<tt/apple2.h/, which is in turn included in <tt/apple2enh.h/.
So it isn't necessary to include it directly. Just
include one of <tt/apple2.h/ or <tt/apple2enh.h/.
<tt/apple2.h/.
The global variable <tt/_datetime/ allows the file creation date/time
to be set before a call to <tt/fopen()/
or <tt/open()/ that creates the file. It is defined in <tt/apple2.h/:
<tscreen>
<verb>
extern struct datetime _datetime;
</verb>
</tscreen>
<tag>Example</tag>
@@ -624,8 +729,8 @@ url="ca65.html" name="assembler manual">.
carriage return instead of a line-feed (Linux/BSD/MacOS) or
carriage return, line-feed pair (Windows).
The "sequential" text file terminology is in contrast to a
"random-access" text file which would
The 'sequential' text file terminology is in contrast to a
'random-access' text file which would
have a fixed-length, non-zero record length, so that the
file position of any individual record can be calculated.

130
doc/apple2enh.sgml
View File

@@ -21,7 +21,8 @@ as it comes with the cc65 C compiler. It describes the memory layout,
enhanced&nbsp;Apple&nbsp;//e specific header files, available drivers, and any
pitfalls specific to that platform.
Please note that enhanced&nbsp;Apple&nbsp;//e specific functions are just mentioned
Please note that this target requires a 65C02 or 65816 CPU,
enhanced&nbsp;Apple&nbsp;//e specific functions are just mentioned
here, they are described in detail in the separate <url 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
@@ -33,7 +34,7 @@ more information.
The standard binary file format generated by the linker for the
enhanced&nbsp;Apple&nbsp;//e target is an <url name="AppleSingle"
url="http://kaiser-edv.de/documents/AppleSingle_AppleDouble.pdf"> file.
url="https://nulib.com/library/AppleSingle_AppleDouble.pdf"> file.
The default load address is &dollar;803.
<bf/AppleCommander 1.4.0/ or later (available at <url
@@ -62,7 +63,7 @@ Special locations:
</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.
However while running module constructors 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
@@ -73,7 +74,7 @@ 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 <ref id="link-configs" name="linker configuration"> parameters. There are
several usefull settings:
several useful settings:
<descrip>
@@ -281,7 +282,7 @@ AppleCommander option to put LOADER.SYSTEM on a ProDOS 8 disk image is <tt/-p/.
If the cc65 program can be successfully linked as system program using the linker
configuration <ref id="apple-sys-cfg" name="apple2enh-system.cfg">, but
uses the heap either explicitly or implicitly (i.e. by loading a driver) then
the memory from &dollar;800 to &dollar;2000 can be added to the heap by calling
the memory from &dollar;800 to &dollar;1FFF can be added to the heap by calling
<tt/_heapadd ((void *) 0x0800, 0x1800);/ at the beginning of <tt/main()/.
@@ -289,9 +290,9 @@ the memory from &dollar;800 to &dollar;2000 can be added to the heap by calling
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.
<url url="funcref.html#posix_memalign" name="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 &dollar;800 and
@@ -321,21 +322,40 @@ Programs containing enhanced&nbsp;Apple&nbsp;//e specific code may use the
<sect1>Enhanced&nbsp;Apple&nbsp;//e specific functions<p>
The functions listed below are special for the enhanced&nbsp;Apple&nbsp;//e. See
the <url url="funcref.html" name="function reference"> for declaration and
The functions and variables listed below are special for the Apple&nbsp;&rsqb;&lsqb;.
See the <url url="funcref.html" name="function reference"> for declaration and
usage.
<itemize>
<item>_auxtype
<item>_dos_type
<item>_filetype
<item>_datetime
<item>beep
<item>dir_entry_count
<item>get_tv
<item>get_ostype
<item>gmtime_dt
<item>mktime_dt
<item>rebootafterexit
<item>ser_apple2_slot
<item>textframe
<item>textframexy
<item>tgi_apple2_mix
<item>videomode
<item>waitvsync
</itemize>
<sect1>Apple IIgs specific functions in accelerator.h<p>
In addition to those, the <tt/accelerator.h/ header file contains three functions
to help determine whether the program is running on a IIgs, and change the IIgs
CPU speed. See the <url url="funcref.html" name="function reference"> for declaration and
usage.
<itemize>
<item>detect_iigs
<item>get_iigs_speed
<item>set_iigs_speed
</itemize>
@@ -377,7 +397,7 @@ The names in the parentheses denote the symbols to be used for static linking of
In memory constrained situations the memory from &dollar;803 to &dollar;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
doesn't use the heap explicitly because loading the driver (and in fact
already opening the driver file) uses the heap implicitly.
</descrip><p>
@@ -428,17 +448,47 @@ The names in the parentheses denote the symbols to be used for static linking of
<descrip>
<tag><tt/a2e.ssc.ser (a2e_ssc_ser)/</tag>
Driver for the Apple&nbsp;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
Driver for the Apple&nbsp;II Super Serial Card.
The SSC is an extension card for the II, II+, IIe; the Apple //c and //c+ have
the same hardware and firmware integrated.
It supports up to 9600 baud, supports no flow control and hardware flow control
(RTS/CTS) and does interrupt driven receives. Speeds faster than 9600 baud
aren't reachable because the ROM and ProDOS IRQ handlers are too slow.
Software flow control (XON/XOFF) is not supported.
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.
Note that using the driver at SER_BAUD_115200 will disable IRQs. It will be up
to the users to use the serial port, either by re-enabling IRQs themselves,
or by directly poll-reading the ACIA DATA register without the help of ser_get().
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&nbsp;II slots, but <tt/ser_open()/ fails with
<tt/SER_ERR_NO_DEVICE/ if there's no SSC firmware found in the selected slot.
In the Apple //c and //c+, slot 1 is the printer port, and slot 2 is the modem
port.
Never call <tt/ser_apple2_slot()/ after <tt/ser_open()/.
<tag><tt/a2e.gs.ser (a2e_gs_ser)/</tag>
Driver for the Apple&nbsp;IIgs serial ports (printer and modem).
It supports up to 9600 baud, supports no flow control and hardware flow control
(RTS/CTS) and does interrupt driven receives. Speeds faster than 9600 baud
aren't reachable because the ROM and ProDOS IRQ handlers are too slow.
Software flow control (XON/XOFF) is not supported.
Note that transmits are not interrupt driven, and the transceiver blocks if
the receiver asserts flow control because of a full buffer.
The driver defaults to opening the modem port. Calling <tt/ser_apple2_slot()/
prior to <tt/ser_open()/ allows to select the printer port (1) or the modem
port (0).
Never call <tt/ser_apple2_slot()/ after <tt/ser_open()/.
</descrip><p>
@@ -550,6 +600,28 @@ program. See the discussion of the <tt/.CONDES/ feature in the <url
url="ca65.html" name="assembler manual">.
<sect1>ProDOS date/time manipulation<p>
<descrip>
The readdir and stat function return ProDOS timestamps in their file
creation/modification time attributes. You can convert them to more portable
time representations using either:
<tag/struct tm/
<tt/struct tm* __fastcall__ gmtime_dt (const struct datetime* dt);/
Converts a <tt/struct datetime/ into a <tt/struct tm/. Returns -1 in case
of error and sets errno, 0 on success.
<tag/time_t/
<tt/time_t __fastcall__ mktime_dt (const struct datetime* dt);/
Parses a <tt/struct datetime/ and returns a UNIX timestamp. Returns 0 on error and
sets errno.
</descrip>
<sect1>DIO<p>
<descrip>
@@ -581,22 +653,20 @@ url="ca65.html" name="assembler manual">.
<tag>Explanation of File Types</tag>
ProDOS associates a file type and an auxiliary type with each file.
ProDOS 8 associates a file type and an auxiliary type with each file.
These type specifications are separate from the file's name, unlike
Windows which uses the file name's suffix (a.k.a.
extension) to specify the file type. For example, <tt/.exe/,
<tt/.doc/, or <tt/.bat/.
The ProDOS low-level
Machine-Language Interface (MLI) functions for creating and opening
files require these types to be specified. And if they don't match
with the file being opened, the operation may fail.
The ProDOS 8 Machine-Language Interface (MLI) function for creating a
file require these types to be specified.
In contrast, the ISO C function <tt/fopen()/ and the POSIX function
<tt/open()/ have no parameter to specify either a file type or an
auxiliary type. Therefore, some additional mechanism for specifying
the file types is needed.
<tag>Specifying the File Type and Auxiliary Type</tag>
<tag>Specifying the File Type, Auxiliary Type and creation date</tag>
There are two global variables provided that allow the file type
and auxiliary type to be specified before a call to <tt/fopen()/
@@ -612,8 +682,16 @@ url="ca65.html" name="assembler manual">.
The header file <tt/apple2_filetype.h/ also defines many values
that can be used to set these variables. It is included in
<tt/apple2.h/, which is in turn included in <tt/apple2enh.h/.
So it isn't necessary to include it directly. Just
include one of <tt/apple2.h/ or <tt/apple2enh.h/.
The global variable <tt/_datetime/ allows the file creation date/time
to be set before a call to <tt/fopen()/
or <tt/open()/ that creates the file. It is defined in <tt/apple2.h/:
<tscreen>
<verb>
extern struct datetime _datetime;
</verb>
</tscreen>
<tag>Example</tag>
@@ -630,8 +708,8 @@ url="ca65.html" name="assembler manual">.
carriage return instead of a line-feed (Linux/BSD/MacOS) or
carriage return, line-feed pair (Windows).
The "sequential" text file terminology is in contrast to a
"random-access" text file which would
The 'sequential' text file terminology is in contrast to a
'random-access' text file which would
have a fixed-length, non-zero record length, so that the
file position of any individual record can be calculated.

50
doc/atari.sgml
View File

@@ -117,7 +117,7 @@ Special locations:
The startup code rearranges the memory as follows:
<enum>
<item>Sceen memory and display list are moved below the program start address.
<item>Screen memory and display list are moved below the program start address.
<item>The ROM is disabled, making the memory in the areas &lsqb;&dollar;C000-&dollar;CFFF&rsqb;
and &lsqb;&dollar;D800-&dollar;FFF9&rsqb; available.
<item>Character generator data is copied from ROM to the CHARGEN location specified in the
@@ -131,7 +131,7 @@ With the default load address of &dollar;2400 this gives a usable memory range o
&lsqb;&dollar;2400-&dollar;CFFF&rsqb;.
Please note that the first load chunk (which checks the system
compatibilty and available memory) will always be loaded at
compatibility and available memory) will always be loaded at
&dollar;2E00, regardless of the specified start address. This address
can only be changed by a custom linker config file.
@@ -305,7 +305,7 @@ The names are the usual ones you can find in system reference manuals. Example:
...
</verb></tscreen>
Please note that memory location 762/$2FA is called "<tt/char_/" while the orignal name "<tt/char/" conflicts with the C keyword.
Please note that memory location 762/$2FA is called "<tt/char_/" while the original name "<tt/char/" conflicts with the C keyword.
If you like to use the OS names and locations for the original Atari 800 operating system, please "<tt/#define OSA/" before including the
<tt/atari.h/ header file.
@@ -332,6 +332,8 @@ See the <url url="funcref.html" name="function reference"> for declaration and u
<item>_scroll
<item>_setcolor
<item>_setcolor_low
<item>_sound
<item>waitvsync
</itemize>
@@ -400,7 +402,7 @@ OS.sdlst = &amp;DisplayList;
...
</verb></tscreen>
Please inspect the <tt/_antic.h/ header file to detemine the supported
Please inspect the <tt/_antic.h/ header file to determine the supported
instruction names. Modifiers on instructions can be nested without need
for an order:
@@ -409,9 +411,10 @@ for an order:
Please mind that ANTIC has memory alignment requirements for "player
missile graphics"-data, font data, display lists and screen memory. Creation
of a special linker configuration with appropriate aligned segments and
switching to that segment in the c-code is usually neccessary. A more memory
hungry solution consists in using the "<tt/posix_memalign()/" function in
conjunction with copying your data to the allocated memory.
switching to that segment in the c-code is usually necessary. A more memory
hungry solution consists in using the <url url="funcref.html#posix_memalign"
name="posix_memalign()"> function in conjunction with copying your data to the
allocated memory.
<sect1>Character mapping<p>
@@ -441,19 +444,7 @@ package delivers the same feature.</em>
You can switch back to the ATASCII mapping by including
"<tt/atari_atascii_charmap.h/".
A final note: Since cc65 has currently some difficulties with string merging
under different mappings, defining remapped strings works only flawlessly
with static array initialization:
<tscreen><verb>
#include &lt;atari_screen_charmap.h&gt;
char pcScreenMappingString[] = "Hello Atari!";
#include &lt;atari_atascii_charmap.h&gt;
char pcAtasciiMappingString[] = "Hello Atari!";
</verb></tscreen>
delivers correct results, while
Example:
<tscreen><verb>
#include &lt;atari_screen_charmap.h&gt;
@@ -463,8 +454,6 @@ char* pcScreenMappingString = "Hello Atari!";
char* pcAtasciiMappingString = "Hello Atari!";
</verb></tscreen>
does not.
<sect1>Keyboard codes<p>
For direct keyboard scanning in conjunction with e.g. the OS location "CH" (764/$2FC),
@@ -674,9 +663,9 @@ The default callbacks definition (<tt/mouse_def_callbacks/) is an alias for the
<sect1>RS232 device drivers<p>
Currently there is one RS232 driver. It uses the R: device (therefore
an R: driver needs to be installed) and was tested with the 850
interface module.
Currently there is one RS232 driver. It supports up to 9600 baud, requires hardware flow control
(RTS/CTS) and uses the R: device (therefore an R: driver needs to be installed). It was tested
with the 850 interface module.
<table>
<tabular ca="rr">
@@ -725,6 +714,11 @@ for sectors 1 to 3, regardless of the type of diskette.
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.
<tt/cprintf/ targets a 40 character line. On a 20-column display this has
the unexpected effect of a blank line after your text. On such displays you can either
use for example <tt/gotoxy(20,0)/ to target the "next" line, or you can switch to <tt/write()/
function which does not have this side effect.
<sect>Technical details<label id="techdetail"><p>
@@ -1140,8 +1134,8 @@ ld65: Error: Missing memory area assignment for segment 'MAINHDR'
</verb></tscreen>
The old "HEADER" memory description contained six bytes: &dollar;FFFF
and the first and last memory addess of the program. For the "system
check" load chunk this had to be split into two memory assigments. The
and the first and last memory address of the program. For the "system
check" load chunk this had to be split into two memory assignments The
"HEADER" now only contains the &dollar;FFFF. The main program's first
and last memory address were moved to a new segment, called "MAINHDR",
which in the new linker config file goes into its own memory area (also
@@ -1169,7 +1163,7 @@ When using cl65, you can leave it out with this command line:
cl65 -Wl -D__SYSTEM_CHECK__=1 <arguments>
</verb></tscreen>
The value you assign to <tt/__SYSTEM_CHECK_/ doesn't matter. If the
The value you assign to <tt/__SYSTEM_CHECK__/ doesn't matter. If the
<tt/__SYSTEM_CHECK__/ symbol is defined, the load chunk won't be included.

65
doc/atari5200.sgml
View File

@@ -30,7 +30,7 @@ information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the Atari 5200 target
The binary output format generated by the linker for the Atari 5200 target
is a cartridge image. It is of course
possible to change this behaviour by using a modified startup file and linker
config.
@@ -73,11 +73,22 @@ Special locations:
Programs containing Atari 5200 specific code may use the <tt/atari5200.h/ header file.
This also includes access to operating system locations (e.g. hardware shadow registers) by a structure called
"<tt/OS/".
The names are the usual ones you can find in system reference manuals. Example:
<tscreen><verb>
...
OS.sdmctl = 0x00; // screen off
OS.color4 = 14; // white frame
tics = OS.rtclok[1] // get ticks
...
</verb></tscreen>
<sect1>Atari 5200 specific functions<p>
<itemize>
<item>TBD.
<item>waitvsync
</itemize>
@@ -208,10 +219,58 @@ you cannot use any of the following functions (and a few others):
<sect>Other hints<p>
AtariROMMaker (<url url="https://www.wudsn.com/index.php/productions-atari800/tools/atarirommaker"> )
<sect1>CAR format<p>
AtariROMMaker (<url url="https://www.wudsn.com/index.php/productions-atari800/tools/atarirommaker"> )
can be used to create a <tt/.CAR/ file from the binary ROM image cc65 generates.
This might be more convenient when working with emulators.
<sect1>Changing the splash screen<p>
The 5200 ROM displays a splash screen at startup with the name of the
game and the copyright year. The year information has a 'Year-2000'
problem, the first two digits are fixed in the ROM and are always "19".
<sect2>Changing the game name<p>
The runtime library provides a default game name which is "cc65
compiled". To change that, one has to link a file which puts data into
the "<tt/CARTNAME/" segment.
For reference, here's the default version used by the cc65 library:
<tscreen><verb>
.export __CART_NAME__: absolute = 1
.macpack atari
.segment "CARTNAME"
scrcode " cc"
.byte '6' + 32, '5' + 32 ; use playfield 1
scrcode " compiled"
</verb></tscreen>
'<tt/__CART_NAME__/' needs to be defined in order that the linker is
satisfied and doesn't try to include the version of the runtime library.
20 bytes are available in the <tt/CARTNAME/ segment (one line) for the
game/program name.
<sect2>Changing the copyright year / changing the cartridge type<p>
The century is hard-coded to 1900 by the ROM.
There are two digits which can be changed. For example "92" will give
"1992" on the screen.
The default used by the runtime library is
<tscreen><verb>
.export __CART_YEAR__: absolute = 1
.segment "CARTYEAR"
.byte '9' + 32,'8' + 32 ; "98", using playfield 1
</verb></tscreen>
If the second byte of the year in the <tt/CARTYEAR/ segment is 255,
the cartridge is seen as a 'diagnostic' cartridge, and the splash
screen and most of the other startup initializations are bypassed.
<sect>License<p>

157
doc/atari7800.sgml Normal file
View File

@@ -0,0 +1,157 @@
<!doctype linuxdoc system>
<article>
<title>Atari 7800 specific information for cc65
<author>
<url url="mailto:karri@sipo.fi" name="Karri Kaksonen"><newline>
<abstract>
An overview over the Atari 7800 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 7800 runtime system as it
comes with the cc65 C compiler. It describes the memory layout, Atari
7800 specific header files and any pitfalls specific to that platform.
<sect>Binary format<p>
The default binary output format generated by the linker for the Atari
7800 target is a 48K cartridge image.
<sect>A78 header<p>
There is lots of different cart hardware available for the atari7800.
Some carts have ROM, RAM, sound hardware, non-volatile high score chips.
In order to know what kind of hardware the cart build requires there is
a header file of 128 bytes in front of the binary.
The default build creates a cart file for a 48K rom cart without any
extra features like the pokey audio chip or extra RAM.
In order to make cc65 more user friendly the build will add the a78
header automatically. This allows you to run the binary on emulators
and flash carts on the real console.
<sect>Encryption<p>
In order to boot the game in a mode that supports atari7800 functions
the cart must be encrypted after the linking phase.
There is a program called sign7800 that can be used to sign the cart.
The encryption is not required for running the cart on emulators.
You can also run atari2600 games without encryption.
<sect>Memory layout<p>
cc65 generated programs with the default setup can use RAM from
from &dollar;1800 to &dollar;203f.
The 4k RAM is then mapped to zero page area.
&dollar;2040 to &dollar;20ff is visible as zero page.
After that we have a vero small RAM area that is unused.
&dollar;2100 to &dollar;213f.
Then we mirror a second block from the RAM to become the hardware stack.
This would be from &dollar;2140 to &dollar;21ff.
The C-stack starts at &dollar;2800 and it can grow down to &dollar;2200.
size of the system stack can be customized by defining the
__STACKSIZE__ linker variable.
Special locations:
<descrip>
<tag/Stack/ The C runtime stack is located at &dollar;2800 -
__STACKSIZE__ and growing downwards.
<tag/Heap/ The C heap is located at &dollar;2200 and grows upwards.
</descrip><p>
<sect>Start-up condition<p>
When powered-up, the Atari 7800 TIA registers contain random
values. During the initialization phase, the start-up code needs to
initialize the TIA registers to sound values (or else the console has
an unpredictable behavior). In this implementation, zeros are written
to all of TIA registers during the start-up phase.
Note that RIOT registers (mostly timers) are left uninitialized, as
they don't have any consequence on the console behavior.
<sect>Platform specific header files<p>
Programs containing Atari 7800 specific code may use the
<tt/atari7800.h/ header file.
The following pseudo variables declared in the <tt/atari7800.h/ header
file allow access to the Atari 7800 TIA, MARIA & RIOT chips registers.
<descrip>
<tag><tt/TIA/</tag> The <tt/TIA/ structure allows read/write access
to the Atari 7800 TIA chip registers. See the <tt/_tia.h/ header
file located in the include directory for the declaration of the
structure. Also refer to the Stella Programmer's Guide by Steve
Wright for a detailed description of the chip and its registers.
<tag><tt/RIOT/</tag> The <tt/RIOT/ structure allows read/write
access to the Atari 7800 RIOT chip registers. See the
<tt/_riot.h/ header file located in the include directory for the
declaration of the structure. Also refer to the Stella Programmer's
Guide by Steve Wright for a detailed description of the chip and its
registers.
<tag><tt/MARIA/</tag> The <tt/MARIA/ structure allows read/write
access to the Atari 7800 MARIA chip registers. See the
<tt/_maria.h/ header file located in the include directory for the
declaration of the structure.
</descrip><p>
<sect>Loadable drivers<p>
There are no drivers for the Atari 7800.
<sect>Limitations<p>
TBD
<sect>Other hints<p>
One may write a custom linker configuration file to tune the memory
layout of a program. See the <tt/atari7800.cfg/ file in the cfg
directory as a starting point.
<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>

17
doc/atmos.sgml
View File

@@ -1,15 +1,15 @@
<!doctype linuxdoc system>
<article>
<title>Oric Atmos-specific information for cc65
<title>Tangerine Oric Atmos-specific information for cc65
<author>
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:polluks@sdf.lonestar.org" name="Stefan A. Haubenthal">,<newline>
<url url="mailto:polluks@sdf.org" name="Stefan A. Haubenthal">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<abstract>
An overview over the Atmos runtime system as it is implemented for the cc65 C
compiler.
An overview over the Oric Atmos runtime system as it is implemented for the cc65
C compiler. This target is not Oric-1 compatible.
</abstract>
<!-- Table of contents -->
@@ -176,10 +176,11 @@ No mouse drivers are currently available for the Atmos.
<tag><tt/atmos-acia.ser (atmos_acia_ser)/</tag>
Driver for the Telestrat integrated serial controller and the Atmos with a
serial add-on.
Note that, because of the peculiarities of the 6551 chip, together with the
use of the NMI, transmits are not interrupt driven; and, the transceiver
blocks if the receiver asserts flow control because of a full buffer.
serial add-on. Supports up to 19200 baud, requires hardware flow control
(RTS/CTS) and does 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>

7
doc/c128.sgml
View File

@@ -133,6 +133,7 @@ declaration and usage.
<item>cbm_save
<item>cbm_write
<item>get_tv
<item>waitvsync
</itemize>
@@ -323,9 +324,9 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c128-
<descrip>
<tag><tt/c128-swlink.ser (c128_swlink_ser)/</tag>
Driver for the SwiftLink cartridge. Supports up to 38400 BPS, 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
Driver for the SwiftLink cartridge. Supports up to 38400 baud, requires hardware
flow control (RTS/CTS) and does 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.

5
doc/c16.sgml
View File

@@ -123,6 +123,7 @@ declaration and usage.
<item>cbm_save
<item>cbm_write
<item>get_tv
<item>waitvsync
</itemize>
@@ -270,7 +271,3 @@ freely, subject to the following restrictions:
</enum>
</article>

13
doc/c64.sgml
View File

@@ -126,7 +126,7 @@ and &dollar;FF3F.
In memory constrained situations the memory from &dollar;400 to &dollar;7FF
can be made available to a program by calling <tt/_heapadd ((void *) 0x0400, 0x0400);/
at the beginning of <tt/main()/. Doing so is beneficial even if the program
doesn't use the the heap explicitly because loading a driver uses the heap implicitly.
doesn't use the heap explicitly because loading a driver uses the heap implicitly.
Using <tt/c64-soft80.o/ is as simple as placing it on the linker command
line like this:
@@ -225,6 +225,7 @@ declaration and usage.
<item>cbm_save
<item>cbm_write
<item>get_tv
<item>waitvsync
</itemize>
@@ -317,6 +318,10 @@ Note that the graphics drivers are incompatible with the
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-kerberos.emd (c64_kerberos_emd)/</tag>
A driver for the Kerberos MIDI Cartridge. The cartridge has 512
pages of 256 bytes for a total of 128KB.
<tag><tt/c64-ram.emd (c64_ram_emd)/</tag>
A driver for the hidden RAM below the I/O area and kernal ROM. Supports 47
256 byte pages. Please note that this driver is incompatible with any of the
@@ -405,9 +410,9 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c64-1
<descrip>
<tag><tt/c64-swlink.ser (c64_swlink_ser)/</tag>
Driver for the SwiftLink cartridge. Supports up to 38400 BPS, 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
Driver for the SwiftLink cartridge. Supports up to 38400 baud, requires hardware
flow control (RTS/CTS) and does 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.

700
doc/ca65.sgml
View File

File diff suppressed because it is too large Load Diff

9
doc/cbm510.sgml
View File

@@ -126,6 +126,7 @@ declaration and usage.
<item>cbm_save
<item>cbm_write
<item>get_tv
<item>waitvsync
</itemize>
@@ -230,10 +231,10 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/cbm51
<tag><tt/cbm510-std.ser (cbm510_std_ser)/</tag>
Driver for the 6551 ACIA chip built into the Commodore 510. Supports up to
19200 BPS, 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.
19200 baud, requires hardware flow control (RTS/CTS) and does 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>

8
doc/cbm610.sgml
View File

@@ -212,10 +212,10 @@ No mouse drivers are currently available for the Commodore 610.
<tag><tt/cbm610-std.ser (cbm610_std_ser)/</tag>
Driver for the 6551 ACIA chip built into the Commodore 610. Supports up to
19200 BPS, 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.
19200 baud, requires hardware flow control (RTS/CTS) and does 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>

73
doc/cc65-intern.sgml
View File

@@ -6,7 +6,8 @@
<abstract>
Internal details of cc65 code generation,
such as calling assembly functions from C.
such as the expected linker configuration,
and calling assembly functions from C.
</abstract>
<!-- Table of contents -->
@@ -16,6 +17,76 @@ such as calling assembly functions from C.
<sect>Linker configuration<p>
The C libraries and code generation depend directly on a suitable linker configuration.
There are premade configuration files in the <tt/cfg&sol;/ directory, normally chosen by the
linker's selected target. These can be used as a template for customization.
The C libraries depend on several special segments to be defined in your linker configuration.
Generated code will also use some of them by default.
Some platform libraries have additional special segments.
Memory areas are free to be defined in a way that is appropriate to each platform,
and the segments they contain are used as a layer of semantics and abstraction,
to allow much of the reorganization to be done with the linker config,
rather than requiring platform-specific code source changes.
<sect1><tt/ZEROPAGE/ segment<p>
Used by the C library and generated code for efficient internal and temporary state storage,
also called "pseudo-registers".
<sect1><tt/STARTUP/ segment<p>
Used by each platform instance of the C library in <tt/crt0.s/ to contain the entry point
of the program.
The startup module will export <tt/__STARTUP__ : absolute = 1/ to force the linker to
always include <tt/crt0.s/ from the library.
<sect1><tt/CODE/ segment<p>
The default segment for generated code, and most C library code will be located here.
Use <tt/#pragma code-name/ to redirect generated code to another segment.
<sect1><tt/BSS/ segment<p>
Used for uninitialized variables.
Originally an acronym for "Block Started by Symbol", but the meaning of this is now obscure.
Use <tt/#pragma bss-name/ to redirect uninitialized variables to another segment.
<sect1><tt/DATA/ segment<p>
Used for initialized variables.
On some platforms, this may be initialized as part of the program loading process,
but on others it may have a separate <tt/LOAD/ and <tt/RUN/ address,
allowing <tt/copydata/ to copy the initialization from the loaded location
into their run destination in RAM.
Use <tt/#pragma data-name/ to redirect initialized variables to another segment.
<sect1><tt/RODATA/ segment<p>
Used for read-only (constant) data.
Use <tt/#pragma rodata-name/ to redirect constant data to another segment.
<sect1><tt/FEATURES/ table<p>
This currently defines table locations for the <tt/CONDES/
constructor, destructor, and interruptor features.
Some platform libraries use these.
The constructors will be called with <tt/initlib/ at startup,
and the destructors with <tt/donelib/ at program exit.
Interruptors are called with <tt/callirq/.
<sect>Calling assembly functions from C<p>
<sect1>Calling conventions<p>

540
doc/cc65.sgml
View File

@@ -6,8 +6,9 @@
<url url="mailto:gregdk@users.sf.net" name="Greg King">
<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.
cc65 is a C compiler for 6502 targets. It supports several 6502-based home
computers such as the Commodore and Atari machines, but it easily is
retargetable.
</abstract>
<!-- Table of contents -->
@@ -60,7 +61,7 @@ Short options:
-Os Inline some standard functions
-T Include source as comment
-V Print the compiler version number
-W warning[,...] Suppress warnings
-W [-+]warning[,...] Control warnings ('-' disables, '+' enables)
-d Debug mode
-g Add debug info to object file
-h Help (this text)
@@ -83,8 +84,9 @@ Long options:
--create-full-dep name Create a full make dependency file
--data-name seg Set the name of the DATA segment
--debug Debug mode
--debug-tables name Write symbol table debug info to a file
--debug-info Add debug info to object file
--debug-opt name Configure optimizations with a file
--debug-opt name Debug optimization steps
--debug-opt-output Debug output of each optimization step
--dep-target target Use this dependency target
--disable-opt name Disable an optimization step
@@ -197,6 +199,189 @@ Here is a description of all the command line options:
Enables debug mode, for debugging the behavior of cc65.
<tag><tt>--debug-tables name</tt></tag>
Writes symbol table information to a file, which includes details on structs, unions
functions, and global variables. For example, given the following code:
<tscreen><verb>
struct l {
unsigned char m;
unsigned char n;
};
struct hello {
unsigned char j;
unsigned char k;
struct l l;
};
struct sub {
unsigned char x;
unsigned char y;
};
union xy {
struct sub xy;
unsigned int mem;
};
typedef struct hello thingy;
unsigned char single;
unsigned char test_local_vars_main(void) {
static unsigned char wahoo;
static unsigned char bonanza = 0x42;
unsigned char i;
unsigned int j;
unsigned int *random;
unsigned char *lol;
signed char whoa;
struct hello wow;
thingy *cool;
union xy xy;
return 0;
}
</verb></tscreen>
The following output would be produced:
<tscreen><verb>
SC_FUNC: _test_local_vars_main: Symbol table
============================================
__fixargs__:
Flags: SC_CONST SC_DEF
Type: unsigned int
__argsize__:
Flags: SC_CONST SC_DEF
Type: unsigned char
wahoo:
AsmName: M0001
Flags: SC_STATIC SC_DEF SC_REF
Type: unsigned char
bonanza:
AsmName: M0002
Flags: SC_STATIC SC_DEF SC_REF
Type: unsigned char
i:
Flags: SC_AUTO SC_DEF SC_REF
Type: unsigned char
j:
Flags: SC_AUTO SC_DEF SC_REF
Type: unsigned int
random:
Flags: SC_AUTO SC_DEF SC_REF
Type: unsigned int *
lol:
Flags: SC_AUTO SC_DEF SC_REF
Type: unsigned char *
whoa:
Flags: SC_AUTO SC_DEF SC_REF
Type: signed char
wow:
Flags: SC_AUTO SC_DEF SC_REF
Type: struct hello
cool:
Flags: SC_AUTO SC_DEF SC_REF
Type: struct hello *
xy:
Flags: SC_AUTO SC_DEF SC_REF
Type: union xy
Global symbol table
===================
thingy:
AsmName: _thingy
Flags: SC_TYPEDEF 0x100000
Type: struct hello
single:
AsmName: _single
Flags: SC_STATIC SC_EXTERN SC_STORAGE SC_DEF SC_REF 0x100000
Type: unsigned char
test_local_vars_main:
AsmName: _test_local_vars_main
Flags: SC_FUNC SC_STATIC SC_EXTERN SC_DEF 0x100000
Type: unsigned char (void)
Global tag table
================
l:
Flags: SC_STRUCT SC_DEF
Type: (none)
hello:
Flags: SC_STRUCT SC_DEF
Type: (none)
sub:
Flags: SC_STRUCT SC_DEF
Type: (none)
xy:
Flags: SC_UNION SC_DEF
Type: (none)
Global struct and union definitions
=========================
SC_STRUCT: l
============
m:
Flags: SC_STRUCTFIELD
Type: unsigned char
n:
Flags: SC_STRUCTFIELD
Type: unsigned char
SC_STRUCT: hello
================
j:
Flags: SC_STRUCTFIELD
Type: unsigned char
k:
Flags: SC_STRUCTFIELD
Type: unsigned char
l:
Flags: SC_STRUCTFIELD
Type: struct l
SC_STRUCT: sub
==============
x:
Flags: SC_STRUCTFIELD
Type: unsigned char
y:
Flags: SC_STRUCTFIELD
Type: unsigned char
SC_UNION: xy
============
xy:
Flags: SC_STRUCTFIELD
Type: struct sub
mem:
Flags: SC_STRUCTFIELD
Type: unsigned int
</verb></tscreen>
<tag><tt>--debug-opt name</tt></tag>
The named file contains a list of specific optimization steps to enable or disable.
@@ -249,7 +434,6 @@ Here is a description of all the command line options:
<item><tt/strcmp()/
<item><tt/strcpy()/
<item><tt/strlen()/
<item>most of the functions declared in <tt/&lt;ctype.h&gt;/
</itemize>
Note: This has two consequences:
@@ -259,9 +443,7 @@ Here is a description of all the command line options:
using <tt/--eagerly-inline-funcs/ actually will 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/).
memory areas larger than 255 bytes.
<p>
</itemize>
@@ -397,7 +579,7 @@ Here is a description of all the command line options:
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
default CPU. The CPU setting can be overridden by use of the <tt/<ref
id="option--cpu" name="--cpu">/ option.
The following target systems are supported:
@@ -449,10 +631,10 @@ Here is a description of all the command line options:
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
faster code, but the code is no longer reentrant as required for recursion.
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)
@@ -548,19 +730,33 @@ Here is a description of all the command line options:
Treat all warnings as errors.
<tag><tt/no-effect/</tag>
Warn about statements that don't have an effect.
<tag><tt/pointer-sign/</tag>
Warn if a pointer assignment changes the signedness of the target
of a pointer value, and the new signedness wasn't cast explicitly.
<tag><tt/pointer-types/</tag>
Warn if a pointer assignment changes the type of the target
of a pointer value, and the new type wasn't cast explicitly.
<tag><tt/remap-zero/</tag>
Warn about a <tt/<ref id="pragma-charmap" name="#pragma charmap()">/
that changes a character's code number from/to 0x00.
<tag><tt/return-type/</tag>
Warn about no return statement in function returning non-void.
<tag><tt/struct-param/</tag>
Warn when passing structs by value.
Warn when passing structs by value. (Disabled by default.)
<tag><tt/unknown-pragma/</tag>
Warn about #pragmas that aren't recognized by cc65.
<tag><tt/unreachable-code/</tag>
Warn about unreachable code in cases of comparing constants, etc.
<tag><tt/unused-func/</tag>
Warn about unused functions.
<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.
<tag><tt/const-overflow/</tag>
Warn if numerical constant conversion implies overflow. (Disabled by default.)
</descrip>
The full list of available warning names can be retrieved by using the
@@ -612,10 +808,12 @@ and the one defined by the ISO standard:
<itemize>
<item> The datatypes "float" and "double" are not available.
Floating point constants may be used, though they will have to be
converted and stored into integer values.
Floating point arithmetic expressions are not supported.
<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.
<item> C Functions may pass and return structs (or unions) by value, but only
of 1, 2 or 4 byte sizes.
<p>
<item> Most of the C library is available with only the fastcall calling
convention (<ref id="extension-fastcall" name="see below">). It means
@@ -626,6 +824,11 @@ and the one defined by the ISO standard:
as it sounds, since the 6502 has so few registers that it isn't
possible to keep values in registers anyway.
<p>
<item> In <tt/cc65/ mode, <tt/main()/ cannot be called recursively. If this
is necessary, the program must be compiled in <tt/c89/ or <tt/c99/ mode
using the <tt><ref id="option--standard" name="--standard"></tt>
command line option.
<p>
</itemize>
There may be some more minor differences I'm currently not aware of. The
@@ -640,21 +843,21 @@ 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
<item> The compiler allows to insert inline assembler code in the form of the
<tt/asm/ expression into the output file. The syntax is
<tscreen><verb>
asm [optional volatile] (&lt;string literal&gt;[, optional parameters]) ;
asm [optional volatile] (&lt;string literal&gt;[, optional parameters])
</verb></tscreen>
or
<tscreen><verb>
__asm__ [optional volatile] (&lt;string literal&gt;[, optional parameters]) ;
__asm__ [optional volatile] (&lt;string literal&gt;[, 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,
There is a whole section covering the inline assembler,
<ref id="inline-asm" name="see there">.
<p>
@@ -709,12 +912,13 @@ This cc65 version has some extensions to the ISO C standard.
places.
<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
<item> There are three pseudo variables named <tt/__A__/, <tt/__AX__/ and
<tt/__EAX__/. They all refer to the primary register that is used
by the compiler to evaluate expressions or return function results.
<tt/__A__/ is of type <tt/unsigned char/, <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>
@@ -795,6 +999,33 @@ This cc65 version has some extensions to the ISO C standard.
size zero, even if it is initialized.
<p>
<item> cc65 supports <tt/_Static_assert/ from C11 and C2X. This is similar
to <tt/#error/ but happens at a later stage of translation, so types
can be used.
<tscreen><verb>
/* C11 version with message. */
_Static_assert (sizeof (int) == 2, "Expected 2-bytes ints.");
/* C2X version without message. */
_Static_assert (sizeof (int) == 2);
</verb></tscreen>
<tt/_Static_assert/ is also available as the macro <tt/static_assert/ in
<tt/assert.h/.
Note: The string literal as the message in the <tt/_Static_assert/
declaration is not subject to string literal translation (see
<tt/<ref id="pragma-charmap" name="#pragma&nbsp;charmap()">/) and will
always be in the host encoding. On the other hand, any character or
string literals present in the condition expression of the
<tt/_Static_assert/ declaration will be translated as usual.
<item> cc65 supports bit-fields of any integral type that is int-sized or
smaller, and enumerated types with those types as their underlying
type. (Only <tt/int/, <tt/signed int/, and <tt/unsigned int/ are
required by the standard.)
<item> Computed gotos, a GCC extension, has limited support. With it you can
use fast jump tables from C. You can take the address of a label with
a double ampersand, putting them in a static const array of type void *.
@@ -822,6 +1053,16 @@ This cc65 version has some extensions to the ISO C standard.
unsigned char foo = 0b101; // sets it to 5
</verb></tscreen>
<item> The character escape '\e', a GCC C extension, is accepted.
In ASCII this is the escape character 0x1B, which may be
remapped in other character sets via a #pragma charmap.
It can be disabled with the <tt><ref id="option--standard"
name="--standard"></tt> option.
<tscreen><verb>
unsigned char foo = '\e'; // sets it to 0x1B or equivalent
</verb></tscreen>
</itemize>
<p>
@@ -888,8 +1129,20 @@ The compiler defines several macros at startup:
<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.14 of the compiler has this macro
defined as <tt/0x02E0/.
compiler in hex: <tt>(VER_MAJOR * 0x100) + VER_MINOR</tt>. The upper 8 bits
are the major-, the lower 8 bits are the minor version. For example, version
47.11 of the compiler would have this macro defined as <tt/0x2f0b/.
Note: until 2.19 this macro was defined as <tt>(VER_MAJOR * 0x100) + VER_MINOR * 0x10</tt> -
which resulted in broken values starting at version 2.16 of the compiler. For
this reason the value of this macro is considered purely informal - you should
not use it to check for a specific compiler version and use different code
according to the detected version - please update your code to work with the
recent version of the compiler instead (There is very little reason to not use
the most recent version - and even less to support older versions in your code).
Should you still insist on doing this for some reason - look at <tt>checkversion.c</tt>
in the samples directory for some preprocessor kludges that might help.
<tag><tt>__CC65_STD__</tt></tag>
@@ -976,25 +1229,46 @@ The compiler defines several macros at startup:
This macro is defined if the target is the Commodore Plus/4 (-t plus4).
<tag><tt>__STDC_HOSTED__</tt></tag>
This macro is expands to the integer constant 1.
<tag><tt>__SIM6502__</tt></tag>
This macro is defined if the target is sim65 in 6502 mode (-t sim6502).
<tag><tt>__SIM65C02__</tt></tag>
This macro is defined if the target is sim65 in 65C02 mode (-t sim65c02).
<tag><tt>__STDC_HOSTED__</tt></tag>
This macro expands to the integer constant 1.
<tag><tt>__STDC_NO_ATOMICS__</tt></tag>
This macro expands to the integer constant 1 if the language standard is cc65 (--standard cc65).
<tag><tt>__STDC_NO_COMPLEX__</tt></tag>
This macro expands to the integer constant 1 if the language standard is cc65 (--standard cc65).
<tag><tt>__STDC_NO_THREADS__</tt></tag>
This macro expands to the integer constant 1 if the language standard is cc65 (--standard cc65).
<tag><tt>__STDC_NO_VLA__</tt></tag>
This macro expands to the integer constant 1 if the language standard is cc65 (--standard cc65).
<tag><tt>__SUPERVISION__</tt></tag>
This macro is defined if the target is the Supervision (-t supervision).
<tag><tt>__SYM1__</tt></tag>
This macro is defined if the target is the Sym-1 (-t sym1).
<tag><tt>__TELESTRAT__</tt></tag>
This macro is defined if the target is the Telestrat (-t telestrat).
<tag><tt>__TIME__</tt></tag>
This macro expands to the time of translation of the preprocessing
@@ -1015,6 +1289,12 @@ 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/.
For all pragma names that contain hyphens, the same name using underlines
instead of the hyphens is available as an alternative. While the former
resembles the corresponding command line option and is more orthogonal, the
latter may be more compatible with external tools that rewrite the token
sequences of the input.
<sect1><tt>#pragma allow-eager-inline ([push,] on|off)</tt><label id="pragma-allow-eager-inline"><p>
@@ -1028,31 +1308,47 @@ parameter with the <tt/#pragma/.
The <tt/#pragma/ understands the push and pop parameters as explained above.
<sect1><tt>#pragma bss-name (&lsqb;push,&rsqb; &lt;name&gt;)</tt><label id="pragma-bss-name"><p>
<sect1><tt>#pragma bss-name ([push, ]&lt;name>[ ,&lt;addrsize>])</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.
This pragma changes the name used for the BSS segment (the BSS segment is
used to store variables with static storage duration and no explicit
initializers). The <tt/name/ argument is a string enclosed in quotation
marks.
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.
<tt/addrsize/ is an optional string that gives a hint about where the
<tt/name/ segment will be put in the CPU's address space. It describes the
width of address numbers that point into that segment. Only words that
are known to ca65 are allowed:
<enum>
<item>"zp", "zeropage", "direct"
<item>"abs", "absolute", "near", "default"
<item>"far"
<item>"long", "dword"
</enum>
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.
Note: The default linker configuration file maps only the standard segments.
If you use other segments, you must create a new linker configuration file.
The <tt/#pragma/ understands the push and pop parameters as explained above.
Beware: The start-up code will zero only the default BSS segment. If you use
another BSS segment, then you must do that yourself; otherwise, variables
with static storage duration and no explicit initializer will not have the
value zero.
Example:
The <tt/#pragma/ understands the push and pop parameters, as explained above.
Examples:
<tscreen><verb>
#pragma bss-name ("MyBSS")
#pragma bss-name ("MyBSS")
#pragma bss-name (push, "MyBSS")
#pragma bss-name ("MyBSS", "zp")
</verb></tscreen>
<sect1><tt>#pragma charmap (&lt;index&gt;, &lt;code&gt;)</tt><label id="pragma-charmap"><p>
Each literal string and each literal character in the source is translated
Each literal string and each literal character in the preprocessed source,
except when used in an <tt/asm/ expression as the inline assembler code or
in a <tt/_Static_assert/ declaration as the failure message, is translated
by use of a translation table. That 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.
@@ -1084,7 +1380,7 @@ parameter with the <tt/#pragma/.
Example:
<tscreen><verb>
/* Use a space wherever an 'a' occurs in ISO-8859-1 source */
#pragma charmap (0x61, 0x20);
#pragma charmap (0x61, 0x20)
</verb></tscreen>
@@ -1102,21 +1398,33 @@ parameter with the <tt/#pragma/.
The <tt/#pragma/ understands the push and pop parameters as explained above.
<sect1><tt>#pragma code-name ([push,] &lt;name&gt;)</tt><label id="pragma-code-name"><p>
<sect1><tt>#pragma code-name ([push, ]&lt;name>[ ,&lt;addrsize>])</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.
This pragma changes the name used for the CODE segment (the CODE segment is
used to store executable code). The <tt/name/ argument is a string enclosed
in quotation marks.
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.
<tt/addrsize/ is an optional string that gives a hint about where the
<tt/name/ segment will be put in the CPU's address space. It describes the
width of address numbers that point into that segment. Only words that
are known to ca65 are allowed:
<enum>
<item>"zp", "zeropage", "direct"
<item>"abs", "absolute", "near", "default"
<item>"far"
<item>"long", "dword"
</enum>
The <tt/#pragma/ understands the push and pop parameters as explained above.
Note: The default linker configuration file maps only the standard segments.
If you use other segments, you must create a new linker configuration file.
Example:
The <tt/#pragma/ understands the push and pop parameters, as explained above.
Examples:
<tscreen><verb>
#pragma code-name ("MyCODE")
#pragma code-name ("MyCODE")
#pragma code-name (push, "MyCODE")
#pragma code-name (push, "MyCODE", "far")
</verb></tscreen>
@@ -1130,21 +1438,33 @@ parameter with the <tt/#pragma/.
The <tt/#pragma/ understands the push and pop parameters as explained above.
<sect1><tt>#pragma data-name ([push,] &lt;name&gt;)</tt><label id="pragma-data-name"><p>
<sect1><tt>#pragma data-name ([push, ]&lt;name>[ ,&lt;addrsize>])</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.
This pragma changes the name used for the DATA segment (the DATA segment is
used to store initialized data). The <tt/name/ argument is a string enclosed
in quotation marks.
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.
<tt/addrsize/ is an optional string that gives a hint about where the
<tt/name/ segment will be put in the CPU's address space. It describes the
width of address numbers that point into that segment. Only words that
are known to ca65 are allowed:
<enum>
<item>"zp", "zeropage", "direct"
<item>"abs", "absolute", "near", "default"
<item>"far"
<item>"long", "dword"
</enum>
The <tt/#pragma/ understands the push and pop parameters as explained above.
Note: The default linker configuration file maps only the standard segments.
If you use other segments, you must create a new linker configuration file.
Example:
The <tt/#pragma/ understands the push and pop parameters, as explained above.
Examples:
<tscreen><verb>
#pragma data-name ("MyDATA")
#pragma data-name ("MyDATA")
#pragma data-name (push, "MyDATA")
#pragma data-name ("MyDATA", "zeropage")
</verb></tscreen>
@@ -1177,7 +1497,7 @@ parameter with the <tt/#pragma/.
This pragma is used to display informational messages at compile-time.
The message intented to be displayed must be a string literal.
The message intended to be displayed must be a string literal.
Example:
<tscreen><verb>
@@ -1206,21 +1526,32 @@ parameter with the <tt/#pragma/.
The <tt/#pragma/ understands the push and pop parameters as explained above.
<sect1><tt>#pragma rodata-name ([push,] &lt;name&gt;)</tt><label id="pragma-rodata-name"><p>
<sect1><tt>#pragma rodata-name ([push, ]&lt;name>[ ,&lt;addrsize>])</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.
This pragma changes the name used for the RODATA segment (the RODATA segment
is used to store read-only data). The <tt/name/ argument is a string enclosed
in quotation marks.
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.
<tt/addrsize/ is an optional string that gives a hint about where the
<tt/name/ segment will be put in the CPU's address space. It describes the
width of address numbers that point into that segment. Only words that
are known to ca65 are allowed:
<enum>
<item>"zp", "zeropage", "direct"
<item>"abs", "absolute", "near", "default"
<item>"far"
<item>"long", "dword"
</enum>
The <tt/#pragma/ understands the push and pop parameters as explained above.
Note: The default linker configuration file maps only the standard segments.
If you use other segments, you must create a new linker configuration file.
Example:
The <tt/#pragma/ understands the push and pop parameters, as explained above.
Examples:
<tscreen><verb>
#pragma rodata-name ("MyRODATA")
#pragma rodata-name ("MyRODATA")
#pragma rodata-name (push, "MyRODATA")
</verb></tscreen>
@@ -1285,7 +1616,7 @@ parameter with the <tt/#pragma/.
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
followed either by "pop", which restores the last pushed state, or by "on" or
"off", optionally preceeded by "push" to push the current state before
"off", optionally preceded by "push" to push the current state before
changing it.
Example:
@@ -1304,17 +1635,27 @@ parameter with the <tt/#pragma/.
This pragma sets a wrapper for functions, often used for trampolines.
The name is a function returning <tt/void/, and taking no parameters.
The <tt/name/ is a wrapper function returning <tt/void/, and taking no parameters.
It must preserve the CPU's <tt/A/ and <tt/X/ registers if it wraps any
<tt/__fastcall__/ functions that have parameters. It must preserve
the <tt/Y/ register if it wraps any variadic functions (they have "<tt/.../"
in their prototypes).
The identifier is an 8-bit number that's set into <tt/tmp4/.
The <tt/identifier/ is an 8-bit number that's set into <tt/tmp4/. If the <tt/identifier/
is "bank", then ca65's <tt><url url="ca65.html#.BANK" name=".bank"></tt> function will be used
to determine the number from the bank attribute defined in the linker config,
see <url url="ld65.html#MEMORY" name="Other MEMORY area attributes">. Note that
this currently implies that only the least significant 8 bits of the bank attribute
can be used.
The address of a wrapped function is passed in <tt/ptr4/. The wrapper can
call that function by using "<tt/jsr callptr4/".
All functions ever declared or defined when this pragma is in effect will be wrapped
when they are called explicitly by their names later in the same translation unit.
Invocation of these functions in any other ways, for example, that via a function
pointer or in inline assembly code, will not be wrapped.
This feature is useful, for example, with banked memory, to switch banks
automatically to where a wrapped function resides, and then to restore the
previous bank when it returns.
@@ -1409,23 +1750,23 @@ 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
The compiler allows to insert inline assembler code in the form of the <tt/asm/
expression into the output file. The syntax is
<tscreen><verb>
asm [optional volatile] (&lt;string literal&gt;[, optional parameters]) ;
asm [optional volatile] (&lt;string literal&gt;[, optional parameters])
</verb></tscreen>
or
<tscreen><verb>
__asm__ [optional volatile] (&lt;string literal&gt;[, optional parameters]) ;
__asm__ [optional volatile] (&lt;string literal&gt;[, 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 <tt/asm/ statement can be used only inside a function. Please note that
the result of an inline assembler expression is always of type <tt/void/.
The <tt/asm/ expression can be used only inside a function. The result of an
<tt/asm/ expression 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 it can be processed further by
@@ -1436,15 +1777,15 @@ even if the ca65 assembler (which is used to translate the generated assembler
code) would accept them. The built-in 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 currently is no way to protect an inline assembler statement
Note: Inline assembler expressions are subject to all optimizations done by the
compiler. There currently is no way to protect an inline assembler expression
-- alone -- from being moved or removed completely by the optimizer. If in
doubt, check the generated assembler output; or, disable optimizations (for
that function).
As a shortcut, you can put the <tt/volatile/ qualifier in your <tt/asm/
statements. It will disable optimization for the functions in which those
<tt/asm volatile/ statements sit. The effect is the same as though you put
expressions. It will disable optimization for the functions in which those
<tt/asm volatile/ expressions sit. The effect is the same as though you put
<tt/#pragma optimize(push, off)/ above those functions, and <tt/#pragma
optimize(pop)/ below those functions.
@@ -1452,6 +1793,13 @@ 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.
Note: The string literal as the inline assembler code itself in the <tt/asm/
expression is not subject to string literal translation (see
<tt/<ref id="pragma-charmap" name="#pragma&nbsp;charmap()">/) and will always
be in the host encoding. On the other hand, all character and string literals
as the arguments for replacing the format specifiers will be translated as
usual.
<itemize>
<item><tt/%b/ - Numerical 8-bit value
<item><tt/%w/ - Numerical 16-bit value
@@ -1539,7 +1887,7 @@ Arrays also can be accessed:
<p>
Note: Do not embed the assembler labels that are used as names of global
variables or functions into your <tt/asm/ statements. Code such as this:
variables or functions into your <tt/asm/ expressions. Code such as this:
<tscreen><verb>
int foo;
@@ -1584,7 +1932,7 @@ This is the original compiler copyright:
Anyone may copy or redistribute these programs, provided that:
1: You don't charge anything for the copy. It is permissable to
1: You don't charge anything for the copy. It is permissible to
charge a nominal fee for media, etc.
2: All source code and documentation for the programs is made

2
doc/chrcvt65.sgml
View File

@@ -19,7 +19,7 @@ the native format.
chrcvt65 is a vector font converter. It is able to convert a "BGI Stroked
Font" to a compact TGI native vector font. See the function <url
url="funcref.html#tgi_load_vectorfont" name="tgi_load_vectorfont"> for usage.
url="tgi.html#tgi_load_vectorfont" name="tgi_load_vectorfont"> for usage.

8
doc/cl65.sgml
View File

@@ -57,11 +57,11 @@ Short options:
-O Optimize code
-Oi Optimize code, inline more code
-Or Optimize code, honour the register keyword
-Os Optimize code, inline standard funtions
-Os Optimize code, inline standard functions
-S Compile but don't assemble and link
-T Include source as comment
-V Print the version number
-W name[,...] Supress compiler warnings
-W name[,...] Suppress compiler warnings
-Wa options Pass options to the assembler
-Wc options Pass options to the compiler
-Wl options Pass options to the linker
@@ -94,7 +94,6 @@ Long options:
--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
@@ -262,6 +261,9 @@ different options for different files on the command line. As an example.
translates main.c with full optimization and module.c with less optimization
and debug info enabled.
Note that the target system (-t , --target) must be specified before any file
unless using the default target of c64
The type of an input file is derived from its extension:
<itemize>

4
doc/co65.sgml
View File

@@ -235,12 +235,12 @@ things to be different from runtime loading:
<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
driver code is no longer contiguous 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
<item> With statically linked code, data and bss segments will get initialized
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

4
doc/coding.sgml
View File

@@ -59,7 +59,7 @@ 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
While in arithmetic operations, chars are immediately 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
@@ -251,7 +251,7 @@ 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
on exit. Saving and 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.

2
doc/customizing.sgml
View File

@@ -140,7 +140,7 @@ FEATURES {
SYMBOLS {
# Define the stack size for the application
__STACKSIZE__: value = $0200, weak = yes;
__STACKSIZE__: value = $0200, type = weak;
}
</code></tscreen>

117
doc/cx16.sgml
View File

@@ -16,15 +16,18 @@ compiler.
<sect>Overview<p>
The Commander X16 is a modern small computer with firmware that is based on
the ROMs in Commodore's VIC-20 and 64C. It has a couple of the I/O chips that
are in the VIC-20.
The Commander X16 is a modern small computer with firmware that is based partly
on the ROMs in Commodore's VIC-20 and 64C. It has a couple of I/O chips
(WDC65C22 VIA) that are like the ones in the VIC-20. It supports file storage
on Secure Digital cards. It allows two joysticks and a mouse. It has three
sound devices. Its VGA screen has twice the range of the C64 (similar to the
C128's 80-column screen), with 256 colors.
This file contains an overview of the CX16 run-time system as it comes with the
cc65 C compiler. It describes the memory layout, CX16-specific header files,
cc65 C compiler. It describes the memory layout, CX16-specific header files,
available drivers, and any pitfalls specific to that platform.
Please note that CX16-specific functions just are mentioned here; they are
Please note that CX16-specific functions just are mentioned here; they might be
described in detail in the separate <url 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
@@ -35,19 +38,20 @@ information.
<sect>Binary format<p>
The standard binary output format generated by the linker for the CX16 target
is a machine language program with a one-line BASIC stub which calls the
machine language part via SYS. That means that a program can be loaded as a
BASIC program, and started with RUN. It is, of course, possible to change that
behaviour by using a modified start-up file and linker config.
is a machine language program that's prepended with a 16-bit load address and a
one-line BASIC stub which calls the machine language part via SYS. That means
that a program can be loaded as a BASIC program, and started with RUN. It is,
of course, possible to change that behaviour by using a modified program-header
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 visible. That means that Kernal entry points can be called directly.
The usable memory ranges are &dollar;0800 - &dollar;9EFF and &dollar;A000 -
&dollar;BFFF.
cc65-generated programs with the default setup run with the I/O area, RAM bank
one, and the Kernal ROM being visible. That means that Kernal entry points
can be called directly. The usable memory ranges are &dollar;0800 -
&dollar;9EFF, &dollar;0400 - &dollar;07FF, and &dollar;A000 - &dollar;BFFF.
Special locations:
@@ -61,7 +65,7 @@ Special locations:
<tag/Bank RAM/
Bank RAM is located at &dollar;A000 - &dollar;BFFF. It's an eight-Kibibyte
window into a half Mibibyte or two Mibibytes of banked RAM.
window into a half Mebibyte or two Mebibytes of banked RAM.
<tag/Bank ROM/
Bank ROM is located at &dollar;C000 - &dollar;FFFF. It's a sixteen-Kibibyte
@@ -76,6 +80,9 @@ The ld65 linker comes with a default config. file for the Commander X16, which
is used via <tt/-t cx16/. The cx16 package comes with additional secondary
linker config. files which are used via <tt/-t cx16 -C &lt;configfile&gt;/.
Those files use 94 bytes in the zero page. (The rest of page zero is reserved
for Kernal and BASIC.)
<sect1>Default config. file (<tt/cx16.cfg/)<p>
@@ -104,7 +111,7 @@ cl65 -o file.prg -t cx16 -C cx16-asm.cfg source.s
To generate code that loads to &dollar;A000:
<tscreen><verb>
cl65 -o file.prg -Wl -S,$A000 -t cX16 -C cX16-asm.cfg source.s
cl65 -o file.prg -Wl -S,$A000 -t cx16 -C cx16-asm.cfg source.s
</verb></tscreen>
It also is possible to add a small BASIC header to the program, that uses SYS
@@ -138,9 +145,17 @@ url="funcref.html" name="function reference"> for declarations and usage.
<item>get_ostype()
<item>set_tv()
<item>videomode()
<item>waitvsync()
<item>vpeek()
<item>vpoke()
</itemize>
<tt/cpeekcolor()/ works differently on the Commander X16 than it does on other
platforms. Each character has two colors: background and text (foreground).
<tt/cpeekcolor()/ returns both colors. The high nybble describes the
background color, the low nybble describes the text color. For example, if the
function is used on the default screen, then it returns &dollar;61, which means
white-on-blue.
<sect1>CBM-specific functions<p>
@@ -157,6 +172,7 @@ declarations and usage.
<item>cbm_k_ckout()
<item>cbm_k_close()
<item>cbm_k_clrch()
<item>cbm_k_getin()
<item>cbm_k_load()
<item>cbm_k_open()
<item>cbm_k_readst()
@@ -173,6 +189,7 @@ declarations and usage.
<item>cbm_save()
<item>cbm_write()
<item>get_tv()
<item>waitvsync()
</itemize>
@@ -183,15 +200,23 @@ access to hardware located in the address space. Some variables are
structures, accessing the struct fields will access the chip registers.
<descrip>
<tag><tt/VERA/</tag>
The <tt/VERA/ structure allows access
to the Video Enhanced Retro Adapter chip.
<tag><tt/RAM_BANK/</tag>
A register that controls which bank of high RAM is visible in the
<tt/BANK_RAM/ window.
<tag><tt/ROM_BANK/</tag>
A register that controls which bank of ROM is active at the moment.
<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 those variables
is explained in <tt/_6522.h/.
<tag><tt/VERA/</tag>
The <tt/VERA/ structure allows access
to the Video Enhanced Retro Adapter chip.
<tag><tt/BANK_RAM/</tag>
A character array that mirrors the eight-Kibibyte window, at &dollar;A000,
into banked RAM.
@@ -201,12 +226,28 @@ structures, accessing the struct fields will access the chip registers.
<sect>Loadable drivers<p>
The names in the parentheses denote the symbols to be used for static linking of the drivers.
The names in the parentheses denote the symbols to be used for static linking
of the drivers. The names fit into the old 8.3-character limit of the SD-Card's
FAT32 file-system.
<sect1>Graphics drivers<p>
No graphics drivers are available currently for the CX16.
The default drivers, <tt/tgi_stddrv (tgi_static_stddrv)/,
point to <tt/cx320p1.tgi (cx320p1_tgi)/.
<descrip>
<tag><tt/cx320p1.tgi (cx320p1_tgi)/</tag>
This driver features a resolution of 320 across and 240 down with 256 colors,
and a slightly adjustable palette (the order of the colors can be changed in
a way that's compatible with some of the other color drivers).
</descrip><p>
<descrip>
<tag><tt/cx640p1.tgi (cx640p1_tgi)/</tag>
This driver features a resolution of 640 across and 480 down with 2 colors,
black and white.
</descrip><p>
<sect1>Extended memory drivers<p>
@@ -217,19 +258,30 @@ No extended memory drivers are available currently for the CX16.
<sect1>Joystick drivers<p>
The default drivers, <tt/joy_stddrv (joy_static_stddrv)/,
point to <tt/cX16-stdjoy.joy (cx16_stdjoy_joy)/.
point to <tt/cx16-std.joy (cx16_std_joy)/.
<descrip>
<tag><tt/cX16-stdjoy.joy (cX16_stdjoy_joy)/</tag>
Supports up to two NES and SNES controllers connected to the joystick ports
of the CX16. It reads the four directions, and the A, B, Select, and Start
buttons. Button A is the primary fire button.
<tag><tt/cx16-std.joy (cx16_std_joy)/</tag>
Supports the keyboard emulation of a controller and up to four SNES (and NES)
controllers connected to the joystick ports of the CX16. It reads the four
directions, and the <bf/A/, <bf/B/, <bf/Select/, and <bf/Start/ buttons.
Buttons <bf/A/ and <bf/B/ are the first and second fire buttons.
</descrip><p>
<sect1>Mouse drivers<p>
No mouse drivers are available currently for the CX16.
The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/,
point to <tt/cx16-std.mou (cx16_std_mou)/.
<descrip>
<tag><tt/cx16-std.mou (cx16_std_mou)/</tag>
Supports a standard 3-button mouse connected to the PS/2 mouse port of the
Commander X16.
Currently, this driver doesn't support <tt/mouse_move()/ and
<tt/mouse_setbox()/.
</descrip><p>
<sect1>RS232 device drivers<p>
@@ -248,9 +300,16 @@ any time. Some changes could make old programs fail to work.
<sect>Other hints<p>
<sect1>STOP and RUN codes<p>
The <tt/Esc/ key acts as Commodore's <tt/STOP/ key -- or, you can press the
<tt/Ctrl/ key and the <tt/C/ key together. Pressing the <tt/Shift/ and the
<tt/Esc/ keys together will type Commodore's <tt/RUN/ key.
<sect1>Escape code<p>
For an Esc, press <tt/Ctrl/ and the <tt/[/ key.
For an <tt/Esc/, press the <tt/Ctrl/ key and the <tt/[/ key together.
<sect1>Passing arguments to the program<p>
@@ -274,7 +333,7 @@ supported directly by BASIC, the following syntax was chosen:
<sect1>Program return code<p>
The program return code (low byte) is passed back to BASIC by use of the
The program return code (low byte) is passed back to BASIC by the use of its
<tt/ST/ variable.

97
doc/da65.sgml
View File

@@ -112,15 +112,17 @@ Here is a description of all the command line options:
<itemize>
<item>6502
<item>6502x
<item>6502dtv
<item>65sc02
<item>65c02
<item>65816
<item>huc6280
<item>4510
</itemize>
6502x is for the NMOS 6502 with unofficial opcodes. huc6280 is the CPU of
the PC engine. 4510 is the CPU of the Commodore C65. Support for the 65816
currently is not available.
6502x is for the NMOS 6502 with unofficial opcodes. 6502dtv is for the
emulated CPU of the C64DTV device. huc6280 is the CPU of the PC engine.
4510 is the CPU of the Commodore C65. 65816 is the CPU of the SNES.
<label id="option--formfeeds">
@@ -154,7 +156,7 @@ Here is a description of all the command line options:
<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
override or replace command line options plus information about the code
that has to be disassembled. See the separate section <ref id="infofile"
name="Info File Format">.
@@ -182,7 +184,7 @@ Here is a description of all the command line options:
<label id="option--mnemonic-column">
<tag><tt>--mnemonic-column n</tt></tag>
Specifies the column where a mnemonic or pseudo instrcuction is output.
Specifies the column where a mnemonic or pseudo instruction is output.
<label id="option--pagelength">
@@ -251,15 +253,19 @@ 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.
manipulation and bit test-and-branch commands. Using 6502x as CPU the illegal
opcodes of 6502 CPU are detected and displayed. 6502dtv setting recognizes the
emulated CPU instructions of the C64DTV device.
When disassembling 4510 code, due to handling of 16-bit wide branches, da65
can produce output that can not be re-assembled, when one or more of those
branches point outside of the disassembled memory. This can happen when text
or binary data is processed.
While there is some code for the 65816 in the sources, it is currently
unsupported.
The 65816 support requires annotating ranges with the M and X flag states.
This can be recorded with an emulator that supports Code and Data Logging,
for example. Disassemble one bank at a time.
<sect1>Attribute map<p>
@@ -277,7 +283,7 @@ 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
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
@@ -298,7 +304,7 @@ name="next section"> for more information.
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
depends on the type of the attribute. String attributes are placed 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
@@ -311,8 +317,8 @@ anything). Each attribute is terminated by a semicolon.
<sect1>Comments<p>
Comments start with a hash mark (<tt/#/) or a double slash (<tt>//</tt>);
and, extend from the position of the mark to the end of the current line.
Comments start with a hash mark (<tt/#/) or a double slash (<tt>//</tt>)
and extend from the position of the mark to the end of the current line.
Hash marks or double slashes inside of strings will <em/not/ start a comment,
of course.
@@ -353,20 +359,20 @@ following attributes are recognized:
<tag><tt/HEXOFFS/</tag>
The attribute is followed by a boolean value. If true, offsets to labels are
This 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
This 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
This 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.
@@ -406,7 +412,7 @@ following attributes are recognized:
<label id="OUTPUTNAME">
<tag><tt/OUTPUTNAME/</tag>
The attribute is followed by string value, which gives the name of the
This 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.
@@ -427,8 +433,8 @@ following attributes are recognized:
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).
the input file. (This assumes that the input file is a ROM that contains the
reset and irq vectors.)
<tag><tt/TEXTCOLUMN/</tag>
@@ -456,12 +462,13 @@ following attributes are recognized:
<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.
start address. Optionally, the end may be given as a decimal offset instead
of an absolute address, "+3", to specify it as a size.
<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>
given name so a separate <tt><ref id="infofile-label" name="LABEL"></tt>
directive is not needed.
<tag><tt>START</tt></tag>
@@ -502,8 +509,8 @@ following attributes are recognized:
<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
the original file, not only because of 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>
@@ -515,6 +522,16 @@ following attributes are recognized:
</descrip>
<tag><tt>UNIT</tt></tag>
Split the table into sections of this size. For example, if you have a
ByteTable of size 48, but it has logical groups of size 16, specifying
16 for UNIT adds newlines after every 16 bytes. UNIT is always in bytes.
<tag><tt>ADDRMODE</tt></tag>
When disassembling 65816 code, this specifies the M and X flag states
for this range. It's a string argument of the form "mx". Capital letters
mean the flag is enabled.
</descrip>
@@ -544,9 +561,9 @@ code. The following attributes are recognized:
<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).
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
@@ -578,15 +595,18 @@ 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.
This attribute is followed by a numerical value which 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 the last address that is a part of the segment.
This attribute is followed by a numerical value which specifies the end
address of the segment. The end address is the last address that is a part of
the segment.
<tag><tt>NAME</tt></tag>
The attribute is followed by a string value which gives the name of the
This attribute is followed by a string value which gives the name of the
segment.
</descrip>
All attributes are mandatory. Segments must not overlap. The disassembler will
@@ -618,10 +638,11 @@ The following attributes are recognized:
<descrip>
<tag><tt>FILE</tt></tag>
Followed by a string value. Specifies the name of the file to read.
This attribute is followed by a string value. It 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
This 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.
@@ -687,6 +708,20 @@ directives explained above:
<sect>Helper scripts<p>
<tt>util/parse-bsnes-log.awk</tt> is a supplied script for 65816 disassembly,
to parse bsnes-plus Code-Data log files and output the RANGE sections
for your info file. For typical usage, you'd check the S-CPU log and trace
log mask boxes in the bsnes-plus debugger, play through the game, then grep
for the bank you're disassembling, and pass that to this script.
<tscreen><verb>
grep ^83 my-game-log | parse-bsnes-log.awk
</verb></tscreen>
<sect>Copyright<p>
da65 (and all cc65 binutils) is (C) Copyright 1998-2011, Ullrich von

17
doc/debugging.sgml
View File

@@ -16,7 +16,7 @@ How to debug your code using the VICE and Oricutron emulators.
<sect>Overview<p>
This document describes how to debug your programs using the cc65 development
tools and the VICE CBM emulator.
tools and the VICE or Oricutron emulator.
@@ -39,7 +39,7 @@ 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
arbitrary 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
@@ -117,7 +117,7 @@ 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
and you may use them wherever you need to specify an address. Try
<tscreen><verb>
d ._main
@@ -126,6 +126,12 @@ and you may use them whereever you need to specify an address. Try
as an example (note that VICE needs a leading dot before all labels, and that
the compiler prepends an underline under most named labels).
If you start the emulator from the commandline, you can also load the labels
directly using something like this:
<tscreen><verb>
x64sc -moncommands hello.lbl hello.prg
</verb></tscreen>
<sect>How to use the label file with Oricutron<p>
@@ -138,14 +144,13 @@ load your label file like this:
</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
and you may use them wherever 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).
as an example.

12
doc/doc.css
View File

@@ -2,12 +2,14 @@ body {
font-family: arial, helvetica, sans-serif;
font-size: 100%;
text-align: justify;
margin-left: 110px;
margin-top: 10px;
margin-right: 30px;
margin-bottom: 10px;
margin: 0px;
padding-left: 110px;
padding-top: 10px;
padding-right: 30px;
padding-bottom: 10px;
background-image: url(doc.png);
background-repeat: repeat-y;
background-position:left top;
}
h1, h2, h2 a:link, h2 a:active, h2 a:visited {
@@ -25,7 +27,7 @@ h1 {
}
h2 {
font-size: 160%;
font-size: 150%;
text-shadow: 1px 1px 3px #303030;
letter-spacing: 1px;
margin-top: 2em;

1088
doc/funcref.sgml
View File

File diff suppressed because it is too large Load Diff

11
doc/gamate.sgml
View File

@@ -3,7 +3,7 @@
<article>
<title>Gamate System specific information for cc65
<author>
<url url="mailto:groepaz@gmx.net" name="Groepaz/Hitmen">
<url url="mailto:groepaz@gmx.net" name="Groepaz">
<abstract>
An overview over the Gamate runtime system as it is implemented for the
@@ -117,14 +117,7 @@ following functions (and a few others):
<sect>Other hints<p>
<itemize>
<item>The Gamate is emulated by MESS (<url url="http://www.mess.org/">),
run like this: <tt>mess gamate -debug -window -skip_gameinfo -cart test.bin</tt>
</itemize>
some resources on the Gamate:
<itemize>
<item><url url="http://en.wikipedia.org/wiki/Gamate">
<item>some resources on the Gamate: <url url="http://en.wikipedia.org/wiki/Gamate">
</itemize>
<sect>License<p>

33
doc/geos.sgml
View File

@@ -205,9 +205,9 @@ see them together in the filling box in GeoPaint.
<sect2>GraphicsString
<p>
<tt/void GraphicsString (char *myGString)/
<tt/void GraphicsString (const void *myGString)/
<p>
One of the more powerfull routines of GEOS. This function calls other graphic functions depending
One of the more powerful 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
@@ -652,7 +652,7 @@ For some purposes you might consider using the <tt/dio.h/ interface to disk acce
<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.
location. If it is nonzero - an error occurred. 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.
@@ -722,9 +722,9 @@ disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/.
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
<sect3>ChkDkGEOS
<p>
<tt/char ChkDskGEOS (void)/
<tt/char ChkDkGEOS (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.
@@ -858,20 +858,21 @@ The functions described here are common for SEQ and VLIR structures.
<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/.
Those 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 is <tt/NULL/ if there are no more slots, or if there was a disk error. The
<tt/_oserror/ variable is non-zero if it was a disk error (see <tt>geos/gdisk.h</tt>). The current
directory track and sector numbers are in <tt/r1L/ and <tt/r1H/. 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/.
This function scans the whole directory for the given filename. It returns either 0 (success), 5
(FILE_NOT_FOUND, defined in <tt>geos/gdisk.h</tt>), 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>
@@ -987,7 +988,7 @@ 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/.
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
@@ -1331,7 +1332,7 @@ This function returns the GEOS Kernal version combined (by logical OR) with the
<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
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

8
doc/grc65.sgml
View File

@@ -7,7 +7,7 @@
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<abstract>
This document describes a compiler that can create GEOS headers and menues for
This document describes a compiler that can create GEOS headers and menus for
cc65-compiled programs.
</abstract>
@@ -24,7 +24,7 @@ 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,
Currently, <bf/grc65/ supports only menus 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).
@@ -270,7 +270,7 @@ required for the correct process of GEOS sequential application building.
<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
Length Index Record) file. When GEOS starts a VLIR overlay application 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.
@@ -345,7 +345,7 @@ for addresses.
<!-- <appendix> -->
<sect>Appendix A -- example.grc<label id="example-grc">
<p><tscreen><verb>
; Note that MENU can define both menues and submenues.
; Note that MENU can define both menus and submenus.
; 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).

14
doc/index.sgml
View File

@@ -59,7 +59,7 @@
Contains hints on creating the most effective code with cc65.
<tag><htmlurl url="cc65-intern.html" name="cc65-intern.html"></tag>
Describes internal details of cc65, such as calling conventions.
Describes internal details of cc65: linker configuration, calling conventions, etc.
<tag><htmlurl url="using-make.html" name="using-make.html"></tag>
Build programs, using the GNU Make utility.
@@ -124,6 +124,9 @@
<tag><htmlurl url="atari5200.html" name="atari5200.html"></tag>
Topics specific to the Atari 5200 Game Console.
<tag><htmlurl url="atari7800.html" name="atari7800.html"></tag>
Topics specific to the Atari 7800 Game Console.
<tag><htmlurl url="atmos.html" name="atmos.html"></tag>
Topics specific to the Oric Atmos.
@@ -151,6 +154,9 @@
<tag><htmlurl url="gamate.html" name="gamate.html"></tag>
Topics specific to the Bit Corporation Gamate Console.
<tag><htmlurl url="kim1.html" name="kim1.html"></tag>
Topics specific to the MOS Technology KIM-1.
<tag><htmlurl url="lynx.html" name="lynx.html"></tag>
Topics specific to the Atari Lynx Game Console.
@@ -169,9 +175,15 @@
<tag><htmlurl url="plus4.html" name="plus4.html"></tag>
Topics specific to the Commodore Plus/4.
<tag><htmlurl url="rp6502.html" name="rp6502.html"></tag>
Topics specific to the Picocomputer 6502.
<tag><htmlurl url="supervision.html" name="supervision.html"></tag>
Topics specific to the Watara Supervision Console.
<tag><htmlurl url="sym1.html" name="sym1.html"></tag>
Topics specific to the Synertek Systems Sym-1.
<tag><htmlurl url="telestrat.html" name="telestrat.html"></tag>
Topics specific to the Oric Telestrat.

96
doc/intro.sgml
View File

@@ -6,6 +6,7 @@
<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:cbmnut@hushmail.com" name="CbmNut">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">,<newline>
<url url="mailto:groepaz@gmx.net" name="Groepaz">,<newline>
<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan M&uuml;hlstrasser">
<abstract>
@@ -409,7 +410,7 @@ Available at <url
url="https://github.com/commanderx16/x16-emulator/releases">:
Emulates the Commander X16 Single Board Computer, with sound, SD card images,
VGA and NTSC video, and a NES game controller emulation. Includes a monitor.
VGA and NTSC video, and a NES game controller emulation. Includes a monitor.
It runs on all SDL2 platforms.
Compile the tutorial with
@@ -458,12 +459,8 @@ Substitute the name of a Commodore computer for that <tt/&lt;sys&gt;/:
Start the desired version of the emulator (CBM610 programs run on
the CBM II &lsqb;<tt/xcbm2/&rsqb; emulator).
In the Windows versions of VICE, choose <bf>File&gt;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/.
Choose <bf>File&gt;Autostart disk/tape image...</bf>, choose your executable,
and click <bf/OK/.
The file has a 14-byte header which corresponds to a PRG-format BASIC program,
consisting of a single line, similar to this:
@@ -499,6 +496,29 @@ The output will appear on a separate line, and you will be returned to a BASIC
prompt.
<sect1>Gamate<p>
Before you can run the cartridge image produced by the linker, the binary has to
be patched using the <bf/gamate-fixcart/ tool that is included in the cc65
package in the util/gamate/ directory.
<tscreen><verb>
gamate-fixcart <image.bin>
</verb></tscreen>
<sect2>MESS<p>
Available at <url
url="https://www.mamedev.org">:
MESS (Multiple Emulator Super System) is a multi system emulator that emulates
various cc65 targets. It once started as a MAME fork, but was marged into MAME
again at some point.
<tscreen><verb>
mess gamate -debug -window -skip_gameinfo -cart <image.bin>
</verb></tscreen>
<sect1>GEOS<p>
Available at <it/Click Here Software's/ <url
url="http://cbmfiles.com/geos/index.html" name="GEOS download section">:
@@ -535,17 +555,8 @@ 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>
In VICE, got to <bf/Settings/ -> <bf/Settings/, then <bf/Peripheral devices/ ->
<bf/Drive/. Then, you must enable the <bf/True drive emulation/ checkbox.
</quote>
Find the <bf/CONVERT/ program on the boot disk &lsqb;tap the 6-key; then, you
@@ -572,6 +583,29 @@ directory notePad. Look at the eight file-positions on each page until you see
The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
reading it.
Alternatively you can use the <bf/c1541/ program that comes with VICE to write the
file to a disk image directly in GEOS format, so it can be used in GEOS directly
without having to use the <bf/CONVERT/ program.
<tscreen><verb>
c1541 -attach geos.d64 -geoswrite hello1
</verb></tscreen>
<sect1>Nintendo Entertainment System<p>
<sect2>Mednafen (NES)<p>
Available at <url
url="https://mednafen.github.io/releases/">:
Mednafen is a multi system emulator that emulates a couple of the supported
targets of cc65: Apple II/II+, Atari Lynx, Nintendo Entertainment System and
PC Engine/TurboGrafx 16.
<tscreen><verb>
mednafen -force_module nes <image.bin>
</verb></tscreen>
<sect1>Ohio Scientific Challenger 1P<p>
The <tt/osic1p/ runtime library returns to the boot prompt when the main()
@@ -694,6 +728,32 @@ Press <RETURN>.
After hitting the RETURN key, you should see the boot prompt again.
<sect1>PC Engine/TurboGrafx 16<p>
For the cartridge image produced by the linker to work in emulators and on real
hardware, its content must be rearranged so the first 8k block becomes the last
8k block in the image.
For example, for a 32k image this can be done using <bf/dd/ as follows:
<tscreen><verb>
dd if=infile.bin bs=8K skip=3 > outfile.pce
dd if=infile.bin bs=8K count=3 >> outfile.pce
</verb></tscreen>
<sect2>Mednafen<p>
Available at <url
url="https://mednafen.github.io/releases/">:
Mednafen is a multi system emulator that emulates a couple of the supported
targets of cc65: Apple II/II+, Atari Lynx, Nintendo Entertainment System and
PC Engine/TurboGrafx 16.
<tscreen><verb>
mednafen -force_module pce <image.pce>
</verb></tscreen>
<sect1>Contributions wanted<p>
We need your help! Recommended emulators and instructions for other targets

150
doc/kim1.sgml Normal file
View File

@@ -0,0 +1,150 @@
<!doctype linuxdoc system>
<article>
<title>MOS Technology KIM-1 specific information for cc65
<author><url url="mailto:davepl@davepl.com" name="Dave Plummer">
<abstract>
An overview of the KIM-1 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 KIM-1 runtime system as it comes with the cc65 C compiler.
It describes the memory layout, KIM-1 specific header files, available drivers, and any pitfalls
specific to the platform.
Please note that KIM-1 specific functions are just mentioned here, they are described in detail
in the separate <url url="funcref.html" name="function reference">. Even functions marked as
&quot;platform dependent&quot; may be available on more than one platform. Please see the
function reference for more information.
<sect>Binary format<p>
The output format generated by the linker for the KIM-1 target is a raw binary BIN file, which
is essentially a memory image. You can convert this to a papertape format file using
Convert8bithexformat or KIMPaper, which are open-source conversion utility programs.
A papertape format files can be transferred to the KIM-1 using the RS-232 terminal port (TTY),
just as if the machine-code was entered by hand. Enter 'L' in the TTY and start the paper tape file
transfer.
<p>
Included with this distribution is a 4k configuration file and a 60k config file. The KIM-1
on-board memory is limited to 4 kbytes but system memory can be increased to 60 kbytes of
contiguous RAM with aftermarket add-on boards. So choose the config file that matches your
system configuration before compiling and linking user programs.
<sect>Memory layout<p>
The ROMs and I/O areas are defined in the configuration files, as are most of the entry points
for useful subroutines in the KIM-1 monitor ROM. cc65 generated programs compiled and linked
using 4k config run in the memory range of &dollar;200 - &dollar;0FFF. The 60k config expands
this range to &dollar;DFFF. When using the 4k config the starting memory location and entry point
for running the program is &dollar;200, so when the program is transferred to the KIM-1, it is
executed by typing '200 G'. With the 60k config the default starting memory location and entry
point is &dollar;2000.
Special locations:
<descrip>
<tag/Text screen/
Conio support is not currently available for the KIM-1. But stdio console functions are available.
<tag/Stack/
The C runtime stack is located at &dollar;0FFF on 4kb KIM-1s, or at &dollar;DFFF for 60kb systems.
The stack always grows 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 KIM-1 code may use the <tt/kim1.h/ header file. See the header file for more information.
<sect>Loadable drivers<p>
<sect1>Graphics drivers<p>
No graphics drivers are currently available for the KIM-1.
<sect1>Joystick drivers<p>
No joystick driver is currently available for the KIM-1.
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the KIM-1.
<sect1>RS232 device drivers<p>
No communication port drivers are currently available for the KIM-1. It has only the &quot;master console&quot;
e.g. stdin and stdout.
<sect>Limitations<p>
<sect1>Disk I/O<p>
The existing library for the KIM-1 doesn't implement C file I/O.
To be more specific, this limitation means that you cannot use any of the following functions (and a few others):
<itemize>
<item>fopen
<item>fclose
<item>fread
<item>fwrite
<item>...
</itemize>
<sect>Other hints<p>
<sect1>kim1.h<p>
This header exposes KIM-1 specific I/O functions that are useful for reading and writing its ports and front panel.
See the <tt/kim1.h/ include file for a list of the functions available.
<sect1>Limited memory applications<p>
As stated earlier, there are config files for 4kb and 60kb systems. If you have 60kb RAM, then you will probably
want to use the kim1-60k configuration, but if not - if you are using the kim1-4k configuration - then you may
want to use functions like getchar, putchar, gets and puts rather than functions like scanf and printf.
Printf, for example, requires about 1KB because it needs to know how to process all the format specifiers.
<sect1>Sample programs<p>
These sample programs can be found in the samples/kim1 directory:
<itemize>
<item>kimHello prints &quot;Hello World!&quot; and then inputs characters, which are echoed on the screen.
This program will run on both 4kb and 60kb systems.</item>
<item>kimSieve finds the prime numbers up to 100,000 using the Sieve of Eratosthenes algorithm, and prints how many
prime numbers were found. This program requires a 60kb system to run.</item>
</itemize>
<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>

248
doc/ld65.sgml
View File

@@ -79,6 +79,7 @@ Long options:
--end-group End a library group
--force-import sym Force an import of symbol 'sym'
--help Help (this text)
--large-alignment Don't warn about large alignments
--lib file Link this library
--lib-path path Specify a library search path
--mapfile name Create a map file
@@ -89,6 +90,7 @@ Long options:
--start-group Start a library group
--target sys Set the target system
--version Print the linker version
--warnings-as-errors Treat warnings as errors
---------------------------------------------------------------------------
</verb></tscreen>
@@ -165,6 +167,7 @@ Here is a description of all of the command-line options:
<item>apple2
<item>apple2enh
<item>atari2600
<item>atari7800
<item>atari
<item>atarixl
<item>atmos
@@ -298,6 +301,12 @@ Here is a description of all of the command-line options:
information generation is currently being developed, so the format of the
file and its contents are subject to change without further notice.
<label id="option--large-alignment">
<tag><tt>--large-alignment</tt></tag>
Disable warnings about a large combined alignment. See the discussion of the
<tt/.ALIGN/ directive in the ca65 Users Guide for further information.
<tag><tt>--lib file</tt></tag>
@@ -322,6 +331,13 @@ Here is a description of all of the command-line options:
directory, in the list of directories specified using <tt/--obj-path/, in
directories given by environment variables, and in a built-in default directory.
<label id="option--warnings-as-errors">
<tag><tt>--warnings-as-errors</tt></tag>
An error will be generated if any warnings were produced.
</descrip>
@@ -753,7 +769,7 @@ There's a library subroutine called <tt/copydata/ (in a module named
look at it's inner workings before using it!
<sect1>Other MEMORY area attributes<p>
<sect1>Other MEMORY area attributes<label id="MEMORY"><p>
There are some other attributes not covered above. Before starting the
reference section, I will discuss the remaining things here.
@@ -815,7 +831,6 @@ 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
@@ -880,7 +895,7 @@ also for a segment. The value must be an integer between 0 and 255. It is used
as the fill value for space reserved by the assembler's <tt/.ALIGN/ and <tt/.RES/
commands. It is also used as the 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.
space that precedes 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 an additional
@@ -914,9 +929,8 @@ name="6502 binary relocation format specification">). It is defined like this:
}
</verb></tscreen>
The other format available is the Atari (xex) segmented file format, this is
the standard format used by Atari DOS 2.0 and upward file managers in the Atari
8-bit computers, and it is defined like this:
The other format available is the Atari segmented file format (xex), this is
the standard format used by Atari DOS 2.0 and upwards, and it is defined like this:
<tscreen><verb>
FILES {
@@ -925,7 +939,8 @@ the standard format used by Atari DOS 2.0 and upward file managers in the Atari
</verb></tscreen>
In the Atari segmented file format, the linker will write each <tt/MEMORY/ area
as a new segment, including a header with the start and end address.
as including a header with the start and end address. If two memory areas are
contiguous, the headers will be joined if possible.
The necessary o65 or Atari attributes are defined in a special section labeled
<ref id="FORMAT" name="FORMAT">.
@@ -1002,7 +1017,8 @@ The <tt/CONDES/ feature has several attributes:
<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.
placed. If the segment does not exist in any object file, it is created
in the final object code.
<tag><tt>type</tt></tag>
@@ -1051,7 +1067,7 @@ The <tt/CONDES/ feature has several attributes:
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 <url
For more information, see the <tt/.CONDES/ command in the <url
url="ca65.html" name="ca65 manual">.
@@ -1132,6 +1148,19 @@ 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 some kind of 'bss' segment since it contains
uninitialized data. Unlike <tt>.bss</tt> itself, its contents aren't
initialized to zero at program startup . It's mostly used by
constructors in the startup code. An example for the use of the INIT
segment is saving/restoring the zero page area used by cc65.
<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>ONCE<p>
The ONCE segment is used for initialization code run only once before
@@ -1139,11 +1168,6 @@ execution reaches main() - provided that the program runs in RAM. You
may for example add the ONCE 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
@@ -1156,6 +1180,202 @@ 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>Debug Info<p>
The debug info and the API mirrors closely the items available in the sources
used to build an executable. To use the API efficiently, it is necessary to
understand from which blocks the information is built.
<itemize>
<item> Libraries
<item> Lines
<item> Modules
<item> Scopes
<item> Segments
<item> Source files
<item> Spans
<item> Symbols
<item> Types
</itemize>
Each item of each type has something like a primary index called an 'id'.
The ids can be thought of as array indices, so looking up something by its
id is fast. Invalid ids are marked with the special value CC65_INV_ID.
Data passed back for an item may contain ids of other objects. A scope for
example contains the id of the parent scope (or CC65_INV_ID if there is no
parent scope). Most API functions use ids to lookup related objects.
<sect1>Libraries<p>
This information comes from the linker and is currently used in only one
place:To mark the origin of a module. The information available for a library
is its name including the path.
<itemize>
<item> Library id
<item> Name and path of library
</itemize>
<sect1>Lines<p>
A line is a location in a source file. It is module dependent, which means
that if two modules use the same source file, each one has its own line
information for this file. While the assembler has also column information,
it is dropped early because it would generate much more data. A line may have
one or more spans attached if code or data is generated.
<itemize>
<item> Line id
<item> Id of the source file, the line is from
<item> The line number in the file (starting with 1)
<item> The type of the line: Assembler/C source or macro
<item> A count for recursive macros if the line comes from a macro
</itemize>
<sect1>Modules<p>
A module is actually an object file. It is generated from one or more source
files and may come from a library. The assembler generates a main scope for
symbols declared outside user generated scopes. The main scope has an empty name.
<itemize>
<item> Module id
<item> The name of the module including the path
<item> The id of the main source file (the one specified on the command line)
<item> The id of the library the module comes from, or CC65_INV_ID
<item> The id of the main scope for this module
</itemize>
<sect1>Scopes<p>
Each module has a main scope where all symbols live, that are specified outside
other scopes. Additional nested scopes may be specified in the sources. So scopes
have a one to many relation: Each scope (with the exception of the main scope) has
exactly one parent and may have several child scopes. Scopes may not cross modules.
<itemize>
<item> Scope id
<item> The name of the scope (may be empty)
<item> The type of the scope: Module, .SCOPE or .PROC, .STRUCT and .ENUM
<item> The size of the scope (the size of the span for the active segment)
<item> The id of the parent scope (CC65_INV_ID in case of the main scope)
<item> The id of the attached symbol for .PROC scopes
<item> The id of the module where the scope comes from
</itemize>
<sect1>Segment Info<p>
<itemize>
<item> Segment id
<item> The name of the segment
<item> The start address of the segment
<item> The size of the segment
<item> The name of the output file, this segment was written to (may be empty)
<item> The offset of the segment in the output file (only if name not empty)
<item> The bank number of the segment's memory area
</itemize>
It is also possible to retrieve the spans for sections (a section is the part of a
segment that comes from one module). Since the main scope covers a whole module, and
the main scope has spans assigned (if not empty), the spans for the main scope of a
module are also the spans for the sections in the segments.
<sect1>Source files<p>
Modules are generated from source files. Since some source files are used several times
when generating a list of modules (header files for example), the linker will merge
duplicates to reduce redundant information. Source files are considered identical if the
full name including the path is identical, and the size and time of last modification
matches. Please note that there may be still duplicates if files are accessed using
different paths.
<itemize>
<item> Source file id
<item> The name of the source file including the path
<item> The size of the file at the time when it was read
<item> The time of last modification at the time when the file was read
</itemize>
<sect1>Spans<p>
A span is a small part of a segment. It has a start address and a size. Spans are used
to record sizes of other objects. Line infos and scopes may have spans attached, so it
is possible to lookup which data was generated for these items.
<itemize>
<item> Span id
<item> The start address of the span. This is an absolute address
<item> The end address of the span. This is inclusive which means if start==end then => size==1
<item> The id of the segment were the span is located
<item> The type of the data in the span (optional, maybe NULL)
<item> The number of line infos available for this span
<item> The number of scope infos available for this span
</itemize>
The last two fields will save a call to cc65_line_byspan or cc65_scope_byspan by providing
information about the number of items that can be retrieved by these calls.
<sect1>Symbols<p>
<itemize>
<item> Symbol id
<item> The name of the symbol
<item> The type of the symbol, which may be label, equate or import
<item> The size of the symbol (size of attached code or data). Only for labels. Zero if unknown
<item> The value of the symbol. For an import, this is taken from the corresponding export
<item> The id of the corresponding export. Only valid for imports, CC65_INV_ID for other symbols
<item> The segment id if the symbol is segment based. For an import, taken from the export
<item> The id of the scope this symbols was defined in
<item> The id of the parent symbol. This is only set for cheap locals and CC65_INV_ID otherwise
</itemize>
Beware: Even for an import, the id of the corresponding export may be CC65_INV_ID.
This happens if the module with the export has no debug information. So make sure
that your application can handle it.
<sect1>Types<p>
A type is somewhat special. You cannot retrieve data about it in a similar way as with the other
items. Instead you have to call a special routine that parses the type data and returns it
in a set of data structures that can be processed by a C or C++ program.
The type information is language independent and doesn't encode things like 'const' or
'volatile'. Instead it defines a set of simple data types and a few ways to aggregate
them (arrays, structs and unions).
Type information is currently generated by the assembler for storage allocating commands
like .BYTE or .WORD. For example, the assembler code
<tscreen><verb>
foo: .byte $01, $02, $03
</verb></tscreen>
will assign the symbol foo a size of 3, but will also generate a span with a size of 3
bytes and a type ARRAY[3] OF BYTE.
Evaluating the type of a span allows a debugger to display the data in the same way as it
was defined in the assembler source.
<table>
<tabular ca="clc">
<bf/Assembler Command/| <bf/Generated Type Information/@<hline>
.ADDR| ARRAY OF LITTLE ENDIAN POINTER WITH SIZE 2 TO VOID@
.BYTE| ARRAY OF UNSIGNED WITH SIZE 1@
.DBYT| ARRAY OF BIG ENDIAN UNSIGNED WITH SIZE 2@
.DWORD| ARRAY OF LITTLE ENDIAN UNSIGNED WITH SIZE 4@
.FARADDR| ARRAY OF LITTLE ENDIAN POINTER WITH SIZE 3 TO VOID@
.WORD| ARRAY OF LITTLE ENDIAN UNSIGNED WITH SIZE 2
</tabular>
</table>
<sect>Copyright<p>

121
doc/library.sgml
View File

@@ -18,22 +18,22 @@ including a discussion of the differences to the ISO standard.
This file contains a short overview of the libraries available for the cc65 C
compiler. Please have a look at the <url 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
reference"> for a function-by-function list. Because the function reference is
not complete (we're working on that), it may happen that you don't find a
specific function. In that 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.
The C library contains a large subset of the ISO C library. Functions usually
are missing in areas where there are no support on typical 6502 systems.
Wide-character sets are an example for that.
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
mentioned here explicitly, expect it to be available, and to behave as defined
in the C standard.
Functions that are <em/not/ available:
@@ -45,13 +45,13 @@ Functions that are <em/not/ available:
<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).
<item>The <tt/ldiv/ function (cc65 currently is not able to return structs,
by value, with a size not equal to 1, 2, or 4 bytes).
<p>
<item>All functions handling wide character strings.
<item>All functions handling wide-character strings.
<p>
<item>Signals and all related functions (having <tt/SIGSEGV/ would be
cool:-)
cool. :-)
<p>
<item><tt>setbuf/setvbuf</tt>
</itemize>
@@ -59,8 +59,11 @@ Functions that are <em/not/ available:
Functions not available on all supported systems:
<itemize>
<item><tt>clock</tt>: Support depends on the capabilities of the target
machine.
<p>
<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
are built on open/read/write/close. Those latter functions are not available
on all systems.
<p>
<item><tt>ftell/fseek/fgetpos/fsetpos</tt>: Support depends on the
@@ -69,94 +72,95 @@ Functions not available on all supported systems:
<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.
<item><tt>time</tt>: Many of the supported systems don't 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
<item><tt>strcspn/strpbrk/strspn</tt>: Those functions have a length
limitation of 256 for the second string argument. Since that string gives a
character set, and there are only 256 distinct characters, that 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/
supported systems, the <tt/getenv/ function always will return a <tt/NULL/
pointer.
<p>
<item><tt>locale</tt>: There is no other locale than the "C" locale. The
<item><tt>locale</tt>: There is no locale other 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:
In addition to those limitations, some more functions are limited if inlined
versions are requested by using the <tt/-Os/ command-line option:
<itemize>
<item>The <tt/strlen/ function only works for strings with a maximum length
<item>The <tt/strlen/ function works for only strings with a maximum length
of 255 characters.
<p>
<item>The <tt/isxxx/ character classification functions from
<item>The <tt/isXXX/ character classification functions from
<tt/&lt;ctype.h&gt;/ will give unpredictable results if the argument is not
in character range (0..255). This limitation may be removed by #undef'ing
in character range (0..255). That 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
that expand to inline assembly code, but the real functions still are
available if the macro definition is removed).
</itemize>
<sect>CPU specific stuff - 6502.h<p>
<sect>CPU-specific stuff - 6502.h<p>
The header file 6502.h contains some functions that make only sense with the
The header file 6502.h contains some functions that make sense only 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>
<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.
For each supported system, there's a header file that contains calls or
defines specific for that system. So, when programming for the C64, include
<tt/&lt;c64.h&gt;/, for the C128, include <tt/&lt;c128.h&gt;/, and so on.
To make the task for the Commodore systems easier, there is also a header file
named <tt/&lt;cbm.h&gt;/ 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 keys (such as function keys)
<item>Defines for special characters (like the graphics characters)
<item>Defines for special characters (such as 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
special hardware. For the C64 and C128, there is a variable struct named
<tt/SID/. Writing to the fields of that struct will write to the SID device
instead. Using those variables will make your program more readable and more
portable. Don't fear ineffective code when using those variables, the
compiler will translate reads and writes to those 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
<item>Other routines that make sense for only a specific system. One example
is routines to write memory locations in the system bank for the CBM-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:
portable. Conio implementations exist for the following targets:
<itemize>
<item>apple2
@@ -165,13 +169,13 @@ portable. conio implementations exist for the following targets:
<item>atari5200
<item>atarixl
<item>atmos
<item>c128
<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>cbm510 (40-column video)
<item>cbm610 (all CBM series-II computers with 80-column video)
<item>creativision
<item>cx16
<item>gamate
<item>geos-apple
<item>geos-cbm
@@ -179,11 +183,12 @@ portable. conio implementations exist for the following targets:
<item>osic1p
<item>pce
<item>pet (all CBM PET systems except the 2001)
<item>plus4 (or expanded c16/c116)
<item>telestrat
<item>vic20
</itemize>
The conio.h header file does also include the system specific header files
The <tt/conio.h/ header file does include the system-specific header files also,
which define constants for special characters and keys.
@@ -191,14 +196,14 @@ 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
read the current value, including constants to evaluate the result of that
function.
<sect>Using a mouse - <tt/mouse.h/<p>
Some target machines support a mouse. Mouse support is currently available for
Some target machines support a mouse. Mouse support currently is available for
the following targets:
<itemize>
@@ -206,19 +211,21 @@ the following targets:
<item>apple2enh
<item>atari
<item>atarixl
<item>c64
<item>c128
<item>c64
<item>cbm510
<item>cx16
</itemize>
The available functions are declared in <tt/mouse.h/.
<sect>Copyright<p>
This C runtime library implementation for the cc65 compiler is (C)
Copyright 1998-2002 Ullrich von Bassewitz. For usage of the binaries
and/or sources the following conditions do apply:
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
@@ -232,8 +239,8 @@ freely, subject to the following restrictions:
<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
appreciated, but is not required.
<item> Altered source versions must be marked plainly 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.

2
doc/lynx.sgml
View File

@@ -36,7 +36,7 @@ Here is a small traditional Hello World program for the Atari Lynx.
<tscreen><verb>
#include <lynx.h>
#include <tgi.h>
#include <6502.h>
#include <6502.h>
void main(void) {
tgi_install(tgi_static_stddrv);

2
doc/nes.sgml
View File

@@ -67,8 +67,8 @@ Programs containing NES specific code may use the <tt/nes.h/ header file.
<sect1>NES specific functions<p>
<itemize>
<item>waitvsync - wait until the start of the next frame</item>
<item>get_tv</item>
<item>waitvsync - wait until the start of the next frame</item>
</itemize>

13
doc/osi.sgml
View File

@@ -187,8 +187,21 @@ Currently the following extra screen configuration modules are implemented:
<itemize>
<item><tt>osic1p-screen-s3-32x28.o</tt>: 32 columns by 28 lines mode
for Briel Superboard ///</item>
<item><tt>osic1p-screen-c1p-48x12.s</tt>: 48 columns by 12 lines mode
for Challenger 1P</item>
</itemize>
On the Briel Superboard /// you enter 32 column mode by holding down
the BREAK key on powerup.
On the Challenger 1P you can enable 48 column mode by writing a 1 to
bit 0 of address &dollar;D800, and writing a 0 to go back to 24 column mode.
You can use code like the following to do this:
<tscreen><verb>
*(char*)0xd800 = 1; /* Switch to 48 column mode */
</verb></tscreen>
<sect>Limitations<p>
<sect1>stdio implementation<p>

9
doc/pce.sgml
View File

@@ -2,7 +2,7 @@
<article>
<title>PC-Engine (TurboGrafx 16) System-specific information for cc65
<author><url url="mailto:groepaz@gmx.net" name="Groepaz/Hitmen">,<newline>
<author><url url="mailto:groepaz@gmx.net" name="Groepaz">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<abstract>
@@ -114,8 +114,8 @@ Programs containing PCE-specific code may use the <tt/pce.h/ header file.
<sect1>PCE-specific functions<p>
<itemize>
<item>waitvsync</item>
<item>get_tv (since all PCE systems are NTSC, this always returns TV_NTSC)</item>
<item>waitvsync</item>
</itemize>
@@ -206,11 +206,6 @@ following functions (and a few others):
<sect>Other hints<p>
<itemize>
<item><url url="https://mednafen.github.io/" name= "Mednafen"> is a good
emulator to use for the PC-Engine.
</itemize>
Some useful resources on PCE coding:
<itemize>

1
doc/pet.sgml
View File

@@ -105,6 +105,7 @@ declaration and usage.
<item>cbm_save
<item>cbm_write
<item>get_tv
<item>waitvsync
</itemize>

9
doc/plus4.sgml
View File

@@ -121,6 +121,7 @@ declaration and usage.
<item>cbm_save
<item>cbm_write
<item>get_tv
<item>waitvsync
</itemize>
@@ -212,10 +213,10 @@ No mouse drivers are currently available for the Plus/4.
<tag><tt/plus4-stdser.ser (plus4_stdser_ser)/</tag>
Driver for the 6551 ACIA chip built into the Plus/4. Supports up to 19200
baud, hardware flow control (RTS/CTS) and interrupt driven receives. Note
that because of the peculiarities of the 6551 chip transmits are not
interrupt driven, and the transceiver blocks if the receiver asserts flow
control because of a full buffer.
baud, requires hardware flow control (RTS/CTS) and does 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.

96
doc/rp6502.sgml Normal file
View File

@@ -0,0 +1,96 @@
<!doctype linuxdoc system>
<article>
<title>Picocomputer 6502 - specific information for cc65
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<abstract>
An overview over the Picocomputer 6502 and its interfaces to the cc65 C
compiler.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview<p>
The Picocomputer 6502 is a modern W65C02S computer with a custom operating
system designed to be POSIX-like. The reference design includes a W65C02S,
W65C22S, RP6502-RIA, and optionally a RP6502-VGA. Peripheral devices like
keyboards, mice, and flash storage are connected by USB to the RP6502-RIA.
Audio is generated by the RP6502-RIA. Video is generated by the RP6502-VGA.
<sect>Binary format<p>
The standard binary output format generated by the linker for the RP6502 target
is a plain machine language program without any prefix or postfix.
The RP6502 Integrated Development Environment, based on Visual Studio Code,
will convert the cc65 binary output into RP6502 ROM files that can be loaded
directly from the RP6502 monitor or installed on the RIA to be loaded at boot.
<sect>Memory layout<p>
<descrip>
<tag/Stack/
The C run-time stack is located at &dollar;FEFF, and grows downward.
<tag/Heap/
The C heap is located at the end of the program, and grows toward the C
run-time stack.
<tag/RAM/
RAM is located at &dollar;0000 - &dollar;FEFF. Default binaries load and
start at &dollar;0200.
<tag/ROM/
The RP6502 is designed with no ROM in the 6502 address space.
<tag/VIA/
A Versatile Interface Adapter (6522) is 16 registers located
at &dollar;FFD0.
<tag/RIA/
The RP6502 Interface Adapter is 32 registers located at &dollar;FFE0.
<tag/User/
User I/O expansion is from &dollar;FF00 to &dollar;FFCF.
</descrip><p>
<sect>Platform-specific header files<p>
Programs containing RP6502-specific code may use the <tt/rp6502.h/ or
<tt/rp6502.inc/ include files.
<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>

287
doc/sim65.sgml
View File

@@ -40,10 +40,19 @@ The simulator is called as follows:
Long options:
--help Help (this text)
--cycles Print amount of executed CPU cycles
--cpu <type> Override CPU type (6502, 65C02, 6502X)
--trace Enable CPU trace
--verbose Increase verbosity
--version Print the simulator version number
</verb></tscreen>
sim65 will exit with the error code of the simulated program,
which is limited to an 8-bit result 0-255.
An error in sim65, like bad arguments or an internal problem will exit with <tt/1/.
A timeout from <tt/-x/ will exit with <tt/2/.
<sect1>Command line options in detail<p>
@@ -63,6 +72,17 @@ Here is a description of all the command line options:
count.
<tag><tt>--cpu &lt;type&gt;</tt></tag>
Specify the CPU type to use while executing the program. This CPU type
is normally determined from the program file header, but it can be useful
to override it.
<tag><tt>--trace</tt></tag>
Print a single line of information for each instruction or interrupt that
is executed by the CPU to stdout.
<tag><tt>-v, --verbose</tt></tag>
Increase the simulator verbosity.
@@ -108,29 +128,78 @@ PVExit ($01)
<sect>Creating a Test in C<p>
For a C test compiled and linked with <tt/--target sim6502/ the
For a C test linked with <tt/--target sim6502/ and the <tt/sim6502.lib/ library,
command line arguments to <tt/sim65/ will be passed to <tt/main/,
and the return value from <tt/main/ will become sim65's exit code.
The <tt/exit/ function may also be used to terminate with an exit code.
Exit codes are limited to 8 bits.
The <tt/stdlib.h/ <tt/exit/ function may also be used to terminate with an exit code.
Exit codes are limited to an unsigned 8 bit value. (E.g. returning -1 will give an exit code of 255.)
The standard C library high level file input and output is functional.
A sim65 application can be written like a command line application,
providing arguments to <tt/main/ and using the <tt/stdio.h/ interfaces.
providing command line arguments to <tt/main/ and using the <tt/stdio.h/ interfaces
to interact with the console or access files.
Internally, file input and output is provided at a lower level by
a set of built-in paravirtualization functions (<ref id="paravirt-internal" name="see below">).
a set of built-in paravirtualization functions (see <ref id="paravirt-internal" name="below">).
Example:
<tscreen><verb>
#include <stdio.h>
int main()
{
printf("Hello!\n");
return 5;
}
// Build and run:
// cl65 -t sim6502 -o example.prg example.c
// sim65 example.prg
// Build and run, separate steps:
// cc65 -t sim6502 -o example.s example.c
// ca65 -t sim6502 -o example.o example.s
// ld65 -t sim6502 -o example.prg example.o sim6502.lib
// sim65 example.prg
</verb></tscreen>
<sect>Creating a Test in Assembly<p>
Assembly tests may similarly be assembled and linked with
<tt/--target sim6502/ or <tt/--target sim65c02/,
and the sim65 library provides an <tt/exit/ symbol that the program may <tt/JMP/
to terminate with the current A register value as an exit code.
Though a C test may also link with assembly code,
a pure assembly test can also be created.
The binary file has a 12 byte header:
Link with <tt/--target sim6502/ or <tt/--target sim65c02/ and the corresponding library,
define and export <tt/_main/ as an entry point,
and the sim65 library provides two ways to return an 8-bit exit code:
<itemize>
<item>Return from <tt/_main/ with the exit code in <tt/A/.
<item><tt/jmp exit/ with the code in <tt/A/. (<tt/.import exit/ from the sim65 library.)
</itemize>
Example:
<tscreen><verb>
.export _main
_main:
lda #5
rts
; Build and run:
; cl65 -t sim6502 -o example.prg example.s
; sim65 example.prg
; Build and run, separate steps:
; ca65 -t sim6502 -o example.o example.s
; ld65 -t sim6502 -o example.prg example.o sim6502.lib
; sim65 example.prg
</verb></tscreen>
Internally, the binary program file has a 12 byte header provided by the library:
<itemize>
@@ -167,8 +236,204 @@ These use cc65 calling conventions, and are intended for use with the sim65 targ
<item><tt/IRQ/ and <tt/NMI/ events will not be generated, though <tt/BRK/
can be used if the IRQ vector at <tt/$FFFE/ is manually prepared by the test code.
<item>The <tt/sim6502/ or <tt/sim65c02/ targets provide a default configuration,
but if customization is needed <tt/sim6502.cfg/ or <tt/sim65c02.cfg/ might be used as a template.
</itemize>
<sect>Counter peripheral
<p>The sim65 simulator supports a memory-mapped counter peripheral that manages
a number of 64-bit counters that are continuously updated as the simulator is
running. For each counter, it also provides a 64 bit "latching" register.
<p>The functionality of the counter peripheral is accessible through 3 registers:
<itemize>
<item><tt>PERIPHERALS_COUNTER_LATCH</tt> ($FFC0, write-only)
<item><tt>PERIPHERALS_COUNTER_SELECT</tt> ($FFC1, read/write)
<item><tt>PERIPHERALS_COUNTER_VALUE</tt> ($FFC2..$FFC9, read-only)
</itemize>
<p>These three registers are used as follows.
<p>When a program explicitly requests a "counter latch" operation by writing any value
to the <tt>PERIPHERALS_COUNTER_LATCH</tt> address ($FFC0), all live registers are simultaneously
copied to the latch registers. They will keep their newly latched values until another latch
operation is requested.
<p>The <tt>PERIPHERALS_COUNTER_SELECT</tt> address ($FFC1) register holds an 8-bit value that
specifies which 64-bit latch register is currently readable through the <tt>PERIPHERALS_COUNTER_VALUE</tt>
address range. Six values are currently defined:
<itemize>
<item>$00: latched clock cycle counter selected.
<item>$01: latched CPU instruction counter selected.
<item>$02: latched IRQ interrupt counter selected.
<item>$03: latched NMI interrupt counter selected.
<item>$80: latched wallclock time (nanoseconds) selected.
<item>$81: latched wallclock time (split: seconds, nanoseconds) selected.
</itemize>
<p>Values $00 to $03 provide access to the latched (frozen) value of their respective live
counters at the time of the last write to <tt>PERIPHERALS_COUNTER_LATCH</tt>.
<p>When <tt>PERIPHERALS_COUNTER_SELECT</tt> equals $80, the <tt>PERIPHERALS_COUNTER_VALUE</tt>
will be a 64-bit value corresponding to the number of nanoseconds elapsed since the Unix epoch
(Midnight, Jan 1st, 1970 UTC), at the time of the last latch operation.
<p>When <tt>PERIPHERALS_COUNTER_SELECT</tt> equals $81, the high 32 bits of <tt>PERIPHERALS_COUNTER_VALUE</tt>
will be a 32-bit value corresponding to the number of seconds elapsed since the Unix epoch (Midnight, Jan 1st,
1970 UTC), at the time of the last latch operation. The low 32 bits of
<tt>PERIPHERALS_COUNTER_VALUE</tt> will hold the nanoseconds since the start of that second.
<p>The two different wallclock-time latch registers will always refer to precisely the same time instant.
For some applications, the single 64-bit value measured in nanoseconds will be more convenient, while
for other applications, the split 32/32 bits representation with separate second and nanosecond
values will be more convenient.
<p>Note that the time elapsed since the Unix epoch is an approximation, as the implementation depends on the
way POSIX defines time-since-the-epoch. Unfortunately, POSIX incorrectly assumes that all days are precisely
86400 seconds long, which is not true in case of leap seconds. The way this inconsistency is resolved is
system dependent.
<p>On reset, <tt>PERIPHERALS_COUNTER_SELECT</tt> is initialized to zero. If the <tt>PERIPHERALS_COUNTER_SELECT</tt>
register holds a value other than one of the six values described above, all <tt>PERIPHERALS_COUNTER_VALUE</tt>
bytes will read as zero.
<p>The <tt>PERIPHERALS_COUNTER_VALUE</tt> addresses ($FFC2..$FFC9) are used to read to currently
selected 64-bit latch register value. Address $FFC2 holds the least significant byte (LSB),
while address $FFC9 holds the most significant byte (MSB).
<p>On reset, all latch registers are reset to zero. Reading any of the <tt>PERIPHERALS_COUNTER_VALUE</tt>
bytes before the first write to <tt>PERIPHERALS_COUNTER_LATCH</tt> will yield zero.
Example:
<tscreen><verb>
/* This example uses the peripheral support in sim65.h */
#include <stdio.h>
#include <sim65.h>
static void print_current_counters(void)
{
peripherals.counter.latch = 0; /* latch values */
peripherals.counter.select = COUNTER_SELECT_CLOCKCYCLE_COUNTER;
printf("clock cycles ............... : %08lx %08lx\n", peripherals.counter.value32[1], peripherals.counter.value32[0]);
peripherals.counter.select = COUNTER_SELECT_INSTRUCTION_COUNTER;
printf("instructions ............... : %08lx %08lx\n", peripherals.counter.value32[1], peripherals.counter.value32[0]);
peripherals.counter.select = COUNTER_SELECT_WALLCLOCK_TIME;
printf("wallclock time ............. : %08lx %08lx\n", peripherals.counter.value32[1], peripherals.counter.value32[0]);
peripherals.counter.select = COUNTER_SELECT_WALLCLOCK_TIME_SPLIT;
printf("wallclock time, split ...... : %08lx %08lx\n", peripherals.counter.value32[1], peripherals.counter.value32[0]);
printf("\n");
}
int main(void)
{
print_current_counters();
print_current_counters();
return 0;
}
</verb></tscreen>
<sect>SIM65 control peripheral
<p>The sim65 simulator supports a memory-mapped peripheral that allows control
of the simulator behavior itself.
<p>The sim65 control peripheral interface consists of 2 registers:
<itemize>
<item><tt>PERIPHERALS_SIMCONTROL_CPUMODE</tt> ($FFCA, read/write)
<item><tt>PERIPHERALS_SIMCONTROL_TRACEMODE</tt> ($FFCB, read/write)
</itemize>
<p>Address <tt>PERIPHERALS_SIMCONTROL_CPUMODE</tt> allows access to the currently active CPU mode.
<p>Possible values are CPU_6502 (0), CPU_65C02 (1), and CPU_6502X (2). For specialized applications,
it may be useful to switch CPU models at runtime; this is supported by writing 0, 1, or 2 to this address.
Writing any other value will be ignored.
<p>Address <tt>PERIPHERALS_SIMCONTROL_TRACEMODE</tt> allows inspection and control of the currently active
CPU tracing mode.
<p>A value of 0 means tracing is disabled; a value of $7F fully enables tracing. The 7
lower bits of the value actually provide control over which fields are printed; see below
for an explanation of the seven fields.
<p>Having the ability to enable/disable tracing on the fly can be a useful debugging aid. For example,
it can be used to enable tracing for short fragments of code. Consider the following example:
<tscreen><verb>
/* This example uses the TRACE_ON and TRACE_OFF macros defined in sim65.h */
#include <stdio.h>
#include <sim65.h>
unsigned x;
int main(void)
{
TRACE_ON();
x = 0x1234; /* We want to see what happens here. */
TRACE_OFF();
return 0;
}
</verb></tscreen>
<p>This small test program, when compiled with optimizations enabled (-O), produces the output trace below:
<tscreen><verb>
70 232 022E A2 12 ldx #$12 A=7F X=00 Y=04 S=FD Flags=nvdizC SP=FFBC
71 234 0230 A9 34 lda #$34 A=7F X=12 Y=04 S=FD Flags=nvdizC SP=FFBC
72 236 0232 8D C8 02 sta $02C8 A=34 X=12 Y=04 S=FD Flags=nvdizC SP=FFBC
73 240 0235 8E C9 02 stx $02C9 A=34 X=12 Y=04 S=FD Flags=nvdizC SP=FFBC
74 244 0238 A9 00 lda #$00 A=34 X=12 Y=04 S=FD Flags=nvdizC SP=FFBC
75 246 023A 8D CB FF sta $FFCB A=00 X=12 Y=04 S=FD Flags=nvdiZC SP=FFBC
</verb></tscreen>
<p>The example output shows the full trace format, consisting of the following seven fields:
<itemize>
<item>The first field is an instruction counter. We see here that the assignment '<tt>x = 0x1234;</tt>'
starts at the 70th CPU instruction since the start of the simulator, and takes four 6502 instructions.
The two instructions that follow correspond to the execution of the <tt>TRACE_OFF</tt>' macro
that disables tracing.
<item>The second field shows the clock cycles since the start of the program. Here we see that the
first four instructions take 12 clock cycles in total (262 - 250 = 12).
<item>The third field shows the program counter as a four-digit, i.e., the PC register. Its 16-bit
value is displayed as a 4-digit hecadecimal number.
<item>The fourth field shows one to three hexadecimal byte values that make up the instruction.
<item>The fifth field shows the instruction in human-readable assembly language.
<item>The sixth field shows the CPU registers before execution of the instruction. The A, X, Y, and
S registers are each shown as a single byte value. The six status bits of the CPU are shown in
the order NVDIZC (Negative, Overflow, Decimal, Interrupt, Zero, Carry). They are displayed as
a capital letter if the flag is set, or a small letter if the flag is unset.
<item>The seventh and last field shows the software stack pointer SP as used by CC65 programs that
conform to the CC65 conventions.
</itemize>
<p>Writing a specific value to <tt>PERIPHERALS_SIMCONTROL_TRACEMODE</tt> will control which of these
seven fields are displayed. The following values are defined to denote the seven fields:
<itemize>
<item>TRACE_FIELD_INSTR_COUNTER = 0x40
<item>TRACE_FIELD_CLOCK_COUNTER = 0x20
<item>TRACE_FIELD_PC = 0x10
<item>TRACE_FIELD_INSTR_BYTES = 0x08
<item>TRACE_FIELD_INSTR_ASSEMBLY = 0x04
<item>TRACE_FIELD_CPU_REGISTERS = 0x02
<item>TRACE_FIELD_CC65_SP = 0x01
</itemize>
<p>For example, writing the value $16 to <tt>PERIPHERALS_SIMCONTROL_TRACEMODE</tt> will only display
the program counter, instruction assembly, and CPU registers fields.
<sect>Copyright<p>

8
doc/smc.sgml
View File

@@ -85,7 +85,7 @@ Please note:
<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
There is no consistency check, if the targeted SMC instruction actually
contains a value. Storing a 'value' on an immplied SMC instruction
would corrupt the following memory cell!
</enum>
@@ -104,7 +104,7 @@ placeholder has two advantages:
<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
placeholders can be better identified: They are fixed and, you may
notice that below, quite eye catching defined.
</enum>
@@ -257,7 +257,7 @@ SMC LoadDefault, { LDX #25 }
<label id="Load value">
<tag><tt>SMC_LoadValue label (, register)</tt></tag>
Retreives the value of a SMC line.
Retrieves the value of a SMC line.
Example:
<tscreen><verb>
@@ -582,7 +582,7 @@ 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
relative 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...

43
doc/sp65.sgml
View File

@@ -44,6 +44,7 @@ Short options:
-lc List all possible conversions
-r file[,attrlist] Read an input file
-v Increase verbosity
-p tgt,file[,attrlist] Write the palette to a file
-w file[,attrlist] Write the output to a file
Long options:
@@ -56,6 +57,7 @@ Long options:
--slice x,y,w,h Generate a slice from the loaded bitmap
--verbose Increase verbosity
--version Print the version number and exit
--palette tgt,file{,attrlist] Write the palette to a file
--write file[,attrlist] Write the output to a file
---------------------------------------------------------------------------
</verb></tscreen>
@@ -124,6 +126,13 @@ attribute lists see <ref id="attr-lists" name="below">.
bugfixes, please include the version number.
<label id="option--palette">
<tag><tt>-p, --palette target,filename[,attrlist]</tt></tag>
Write the palette of the input bitmap to a file in a format suitable of
the target.
<label id="option--write">
<tag><tt>-w, --write filename[,attrlist]</tt></tag>
@@ -265,6 +274,7 @@ 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.
You can also force the number of pens used in the conversion.
There are a few attributes that you can give to the conversion software.
@@ -273,7 +283,7 @@ There are a few attributes that you can give to the conversion software.
<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.
"shaped". 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
@@ -290,10 +300,26 @@ There are a few attributes that you can give to the conversion software.
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.
The last encoding mode "shaped" is like packed. But we can stop the conversion
to the right abd left edge when we get the first "edge" colour. If no edge
colour is specified we stop at the first index 0 colour.
If your edge index is outside the range 0..15 then your sprite can use all
the colours in the defined palette.
This will also produce the smallest sprite possible on the Lynx. The sprite
is not rectangular anymore.
<tag/edge/
This keyword is only meaningful for shaped sprites. By default it is 0.
The shaped sprite outer edge is defined by the colour index "edge".
<tag/pen/
This keyword defines the order the colours in the original bitmap is
mapped to the Lynx sprite. The length of the pen also defines the depth
of the generated sprite.
If you want to create a 1 BPP sprite you can define the two indices used
in the sprite like pen=34. Now areas in colour index 3 will be mapped as 0.
Areas in colour index 4 will be mapped as 1.
The default pen=0123456789abcdef.
<tag/ax/
The sprite is painted around the Anchor point. The anchor point x can be
@@ -301,7 +327,9 @@ There are a few attributes that you can give to the conversion software.
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).
around the anchor point. You can also define the location using the words
"mid" for the center or "max" for the right edge.
The default value is 0 (left).
<tag/ay/
The sprite is painted around the Anchor point. The anchor point y can be
@@ -309,7 +337,8 @@ There are a few attributes that you can give to the conversion software.
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).
around the anchor point. You can also define the location using the words
"mid" for the center or "max" for the bottom. The default value is 0 (top).
</descrip>

173
doc/sym1.sgml Normal file
View File

@@ -0,0 +1,173 @@
<!doctype linuxdoc system>
<article>
<title>Synertek Systems Sym-1 specific information for cc65
<author><url url="mailto:wayne@parhamdata.com" name="Wayne Parham">
<abstract>
An overview over the Sym-1 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 Sym-1 runtime system as it comes with the cc65 C compiler.
It describes the memory layout, Sym-1 specific header files, available drivers, and any pitfalls
specific to the platform.
Please note that Sym-1 specific functions are just mentioned here, they are described in detail
in the separate <url url="funcref.html" name="function reference">. Even functions marked as
&quot;platform dependent&quot; may be available on more than one platform. Please see the
function reference for more information.
<sect>Binary format<p>
The output format generated by the linker for the Sym-1 target is a raw binary BIN file, which
is essentially a memory image. You can convert this to a HEX file using BIN2HEX, which is a
popular open-source conversion utility program. A HEX file has ASCII representations of the
hexadecimal byte values of the machine-language program. So the HEX file can be transferred
to the Sym-1 using the RS-232 terminal port, just as if the machine-code was entered by hand.
Enter 'm 200' in the monitor and start the HEX file transfer.
<p>
Included with this distribution is a 4k configuration file and a 32k config file. The Sym-1
on-board memory is limited to 4 kbytes but system memory can be increased to 32 kbytes of
contiguous RAM with aftermarket add-on boards. So choose the config file that matches your
system configuration before compiling and linking user programs.
<sect>Memory layout<p>
The ROMs and I/O areas are defined in the configuration files, as are most of the entry points
for useful subroutines in the Sym-1 monitor ROM. cc65 generated programs compiled and linked
using 4k config run in the memory range of &dollar;200 - &dollar;0FFF. The 32k config expands
this range to &dollar;7FFF. Memory above 32k can be used to extend the heap, as described below.
The starting memory location and entry point for running the program is &dollar;200, so when the
program is transferred to the Sym-1, it is executed by typing 'g 200'. The system returns control
back to the monitor ROM when the program terminates, providing the '.' prompt.
Special locations:
<descrip>
<tag/Text screen/
Conio support is not currently available for the Sym-1. But stdio console functions are available.
<tag/Stack/
The C runtime stack is located at &dollar;0FFF on 4kb Syms, or at &dollar;7FFF for 32kb systems.
The stack always grows downwards.
<tag/Heap/
The C heap is located at the end of the program and grows towards the C runtime stack. Extended
memory can be added to the heap, as described below.
</descrip><p>
<sect>Platform specific header files<p>
Programs containing Sym-1 code may use the <tt/sym1.h/ header file. See the header file for more information.
<sect1>Hardware access<p>
The pseudo variables declared in the <tt/sym1.inc/ include file allow access to hardware located in the
address space. See the include file for more information.
<sect>Loadable drivers<p>
<sect1>Graphics drivers<p>
No graphics drivers are currently available for the Sym-1.
<sect1>Extended memory drivers<p>
There are no extended memory drivers for the Sym-1. However, there is a way to access memory beyond the
32kb boundary, if extended memory is physically present in the system. See the example program,
symExtendedMemory, in the samples directory.
<sect1>Joystick drivers<p>
No joystick driver is currently available for the Sym-1.
<sect1>Mouse drivers<p>
No mouse drivers are currently available for the Sym-1.
<sect1>RS232 device drivers<p>
No communication port drivers are currently available for the Sym-1. It has only the &quot;master console&quot;
e.g. stdin and stdout.
<sect>Limitations<p>
<sect1>Disk I/O<p>
The existing library for the Sym-1 doesn't implement C file I/O.
To be more specific, this limitation means that you cannot use any of the following functions (and a few others):
<itemize>
<item>fopen
<item>fclose
<item>fread
<item>fwrite
<item>...
</itemize>
<sect>Other hints<p>
<sect1>sym1.h<p>
This header exposes Sym-specific I/O functions that are useful for reading and writing its ports and front panel.
See the <tt/sym1.h/ include file for a list of the functions available.
<sect2>Limited memory applications<p>
As stated earlier, there are config files for 4kb and 32kb systems. If you have 32kb RAM, then you will probably
want to use the sym1-32k configuration, but if not - if you are using the sym1-4k configuration - then you may
want to use functions like getchar, putchar, gets and puts rather than functions like scanf and printf.
Printf, for example, requires about 1KB because it needs to know how to process all the format specifiers.
<sect3>Using extended memory<p>
Memory may be physically present that is addressed at locations above the monitor ROM at $8000. This extended
memory is accessible by adding to the heap, as described in the symExtendedMemory sample program.
<sect4>Sample programs<p>
All the samples will run on the &quot;stock&quot; 4kb Sym-1, except for symIO and symNotepad, which require 32kb.
Additionally, symExtendedMemory shows how to access memory above 32kb, so it expects more than 32kb.
These sample programs can be found in the samples/sym1 directory:
<itemize>
<item>symHello prints &quot;Hello World!&quot; and then inputs characters, which are echoed on the screen.
It also makes a &quot;beep&quot; sound.</item>
<item>symTiny does the same as symHello, but does it with puts() rather than printf() to show the difference
in compiled binary size.</item>
<item>symDisplay allows entry of a message, which is then displayed by scrolling it across the front panel display.</item>
<item>symIO allows access to the Sym-1 digital I/O ports.</item>
<item>symNotepad is a simple text entry/retrieval program that uses tape storage.</item>
<item>symExtendedMemory demonstrates how to access upper-memory and add it to the heap.</item>
</itemize>
<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>

25
doc/telestrat.sgml
View File

@@ -79,7 +79,7 @@ in Telemon, there is no way to load a binary easily.
Stratsed (the Telestrat operating system) handles files management. Stratsed
is loaded to memory from floppy disk. Stratsed vector are declared in asminc/telestrat.inc.
But, reverse engineering is required to find how theses vectors works. Please, note that
But, reverse engineering is required to find how these vectors works. Please, note that
Stratsed is located in overlay memory (bank 0)
There is no tool to insert a binary in a Stratsed floppy disk.
@@ -189,15 +189,20 @@ port cardridge.
<sect1>Joystick drivers<p>
Telemon 2.4 & 3.0 manages joysticks but it had been handled yet. This means that
joysticks driver could be written easily.
Telemon 2.4 returns in keyboard buffer the direction of the joysticks. This means that
if you get input from keyboard by conio cgetc function, you will get direction from joysticks.
Anyway, if you don't want to use ROM, you can use joysticks standard drivers in your code.
The standard driver manages two joysticks. Only one button is managed for these joysticks.
Telestrat can handle one button for the left port, and three buttons for the right port (but this port was designed for a mouse).
If you find a Telestrat mouse (which is almost impossible :), these driver will work too because there is some extra hardware in the mouse to send direction.
<sect1>Mouse drivers<p>
Telestrat manages also mouse, but it had been no handled yet in this version.
Telestrat manages also mouse (Joystick port)
Telestrat mouse is really difficult to find.
<sect1>RS232 device drivers<p>
@@ -212,7 +217,7 @@ RS232 port with Telemon calls (see XSOUT primitive for example)
Telemon 3.0 handles fopen, fread, fclose primitives. It means that this
function will crash the Telestrat because Telemon 2.4 does not have these
primitives. By the way, Telemon 3.0 uses an extension "ch376 card" which
handles sdcard and FAT 32 usb key. In the next version of Telemon, FT DOS,
handles sdcard and FAT 32 usb key. In the next version of Telemon, FT DOS,
Sedoric, Stratsed will be handled in these 3 primitives (fopen, fread, fclose).
<itemize>
@@ -222,10 +227,10 @@ Sedoric, Stratsed will be handled in these 3 primitives (fopen, fread, fclose).
</itemize>
<sect1>conio<p>
Functions textcolor and bgcolor are available only with Telemon 3.0 (Orix).
Telemon 2.4 primitives can't handle any change of colors in text mode except with XINK or
XPAPER primitives which put on the first and second columns ink and paper attributes.
The only way to change color on the same line for text is to handle it in pure assembly
Functions textcolor and bgcolor are available only with Telemon 3.0 (Orix).
Telemon 2.4 primitives can't handle any change of colors in text mode except with XINK or
XPAPER primitives which put on the first and second columns ink and paper attributes.
The only way to change color on the same line for text is to handle it in pure assembly
without systems calls.
<sect>Other hints<p>

94
doc/tgi.sgml
View File

@@ -41,11 +41,11 @@ of range.
<ref id="tgi_ellipse" name="tgi_ellipse">,
<ref id="tgi_pieslice" name="tgi_pieslice">,
<ref id="tgi_setcolor" name="tgi_setcolor">
<tag/Example/<verb>
<tag/Example/<tscreen><verb>
/* Draw the upper half of an ellipse */
tgi_setcolor(TGI_COLOR_BLUE);
tgi_arc (50, 50, 40, 20, 0, 180);
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -66,10 +66,10 @@ be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi function
<tag/Example/<verb>
<tag/Example/<tscreen><verb>
tgi_setcolor(TGI_COLOR_GREEN);
tgi_bar(10, 10, 100, 60);
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -93,10 +93,10 @@ be used in presence of a prototype.
<ref id="tgi_ellipse" name="tgi_ellipse">,
<ref id="tgi_pieslice" name="tgi_pieslice">,
<ref id="tgi_setcolor" name="tgi_setcolor">
<tag/Example/<verb>
<tag/Example/<tscreen><verb>
tgi_setcolor(TGI_COLOR_BLACK);
tgi_circle(50, 40, 40);
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -153,10 +153,10 @@ be used in presence of a prototype.
<ref id="tgi_circle" name="tgi_circle">,
<ref id="tgi_pieslice" name="tgi_pieslice">,
<ref id="tgi_setcolor" name="tgi_setcolor">
<tag/Example/<verb>
<tag/Example/<tscreen><verb>
tgi_setcolor(TGI_COLOR_RED);
tgi_ellipse (50, 40, 40, 20);
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -227,9 +227,9 @@ 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>
<tag/Example/<tscreen><verb>
color = tgi_getcolor();
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -241,15 +241,40 @@ color = tgi_getcolor();
<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
<tag/Description/TGI platforms use indexed color palettes. This function
returns the number of entries we can use in the palette.
<tt/tgi_setcolor()/ can accept numbers from <tt/0/ to <tt/255/. That is 256
possible colors, but an <tt/(unsigned char)/ cannot hold that number.
Therefore, the number zero is used to indicate when a palette has 256 entries.
A portable program should test for that number, and do appropriate actions.
A program might assign the count to an <tt/unsigned int/ (and change a zero to
a 256). Or, it might rely on the fact that <tt/(unsigned char)/ will
"wrap-around" when it is incremented beyond 255.
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/<verb>
<tag/See also/<ref id="tgi_getcolor" name="tgi_getcolor()">,
<ref id="tgi_getdefpalette" name="tgi_getdefpalette()">,
<ref id="tgi_getmaxcolor" name="tgi_getmaxcolor()">,
<ref id="tgi_getpalette" name="tgi_getpalette()">,
<ref id="tgi_setcolor" name="tgi_setcolor()">,
<ref id="tgi_setpalette" name="tgi_setpalette()">
<tag/Examples/<tscreen><verb>
if (tgi_getcolorcount() == 2) {
printf("Only monochrome graphics is supported\n");
}
</verb>
static unsigned char num_colors;
static unsigned char color;
...
num_colors = tgi_getcolorcount();
...
++color;
if (num_colors == 0) {
tgi_setcolor(color);
} else {
tgi_setcolor(color % num_colors);
}
</verb></tscreen>
</descrip>
</quote>
@@ -316,7 +341,12 @@ be used in presence of a prototype.
<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/See also/<ref id="tgi_getcolor" name="tgi_getcolor()">,
<ref id="tgi_getcolorcount" name="tgi_getcolorcount()">,
<ref id="tgi_getdefpalette" name="tgi_getdefpalette()">,
<ref id="tgi_getpalette" name="tgi_getpalette()">,
<ref id="tgi_setcolor" name="tgi_setcolor()">,
<ref id="tgi_setpalette" name="tgi_setpalette()">
<tag/Example/None.
</descrip>
</quote>
@@ -447,10 +477,10 @@ be used in presence of a prototype.
<quote>
<descrip>
<tag/Function/Get number of horisontal pixels on the screen.
<tag/Function/Get number of horizontal 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.
<tag/Description/Get number of horizontal pixels on the screen.
This is same as tgi_maxx()+1.
<tag/Availability/cc65
<tag/See also/Other tgi functions.
@@ -511,10 +541,10 @@ name="tgi_clear">/ after <tt/tgi_init/.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/<verb>
<tag/Example/<tscreen><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>
</verb></tscreen>
</descrip>
</quote>
@@ -525,7 +555,7 @@ tgi_init(); //Set up the default palette and clear the screen.
<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/Declaration/<tt/unsigned char __fastcall__ tgi_install (const 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).
@@ -538,10 +568,10 @@ used in presence of a prototype.
<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>
<tag/Example/<tscreen><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>
</verb></tscreen>
</descrip>
</quote>
@@ -587,7 +617,7 @@ be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/<verb>
<tag/Example/<tscreen><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))
@@ -600,7 +630,7 @@ if (!tgi_busy()) {
tgi_outttextxy(20,40,"Hello World");
tgi_updatedisplay();
}
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -759,11 +789,11 @@ of range.
<ref id="tgi_circle" name="tgi_circle">,
<ref id="tgi_ellipse" name="tgi_ellipse">,
<ref id="tgi_setcolor" name="tgi_setcolor">
<tag/Example/<verb>
<tag/Example/<tscreen><verb>
/* Draw the closed upper half of an ellipse */
tgi_setcolor(TGI_COLOR_BLUE);
tgi_pieslice (50, 50, 40, 20, 0, 180);
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -814,12 +844,12 @@ be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/<verb>
<tag/Example/<tscreen><verb>
tgi_setcolor(TGI_COLOR_BLACK);
tgi_bar(0,0,30,30);
tgi_setcolor(TGI_COLOR_WHITE);
tgi_bar(10,10,20,20);
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -841,7 +871,7 @@ be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/<verb>
<tag/Example/<tscreen><verb>
tgi_setdrawpage(1);
tgi_outtextxy(10, 10, "Hello World");
tgi_setviewpage(1); // Show page 1
@@ -849,7 +879,7 @@ tgi_setdrawpage(0);
tgi_outtextxy(10, 10, "Creating next frame");
...
tgi_setviewpage(0); // Show page 0
</verb>
</verb></tscreen>
</descrip>
</quote>
@@ -953,7 +983,7 @@ be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/Example/<verb>
<tag/Example/<tscreen><verb>
tgi_setdrawpage(1);
tgi_outtextxy(10, 10, "Hello World");
tgi_setviewpage(1); // Show page 1
@@ -961,7 +991,7 @@ tgi_setdrawpage(0);
tgi_outtextxy(10, 10, "Creating next frame");
...
tgi_setviewpage(0); // Show page 0
</verb>
</verb></tscreen>
</descrip>
</quote>

6
doc/using-make.sgml
View File

@@ -76,13 +76,13 @@ ifneq ($(MAKECMDGOALS),clean)
endif
%.o: %.c
$(CC) -c $(CFLAGS) -o $@ $<
&#9;$(CC) -c $(CFLAGS) -o $@ $<
$(PROGRAM): $(SOURCES:.c=.o)
$(CC) $(LDFLAGS) -o $@ $^
&#9;$(CC) $(LDFLAGS) -o $@ $^
clean:
$(RM) $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map
&#9;$(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

30
doc/vic20.sgml
View File

@@ -75,7 +75,6 @@ common to all CBM platforms.
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
@@ -107,6 +106,7 @@ declaration and usage.
<item>cbm_save
<item>cbm_write
<item>get_tv
<item>waitvsync
</itemize>
@@ -142,7 +142,33 @@ The names in the parentheses denote the symbols to be used for static linking of
<sect1>Graphics drivers<p>
No graphics drivers are currently available for the VIC20.
<descrip>
<tag><tt/vic20-hi.tgi (vic20_hi_tgi)/</tag>
This driver features a resolution of 160&times;192 with two colors. The
background can be chosen from a sixteen-color palette. The foreground can
be chosen from an eight-color palette.
The driver will use memory from addresses $1000 to $1FFF as a graphics
buffer. Therefore, the VIC-20 must have, at least, 8K of expansion RAM.
Programs that use this driver must be linked by the <tt/vic20-tgi.cfg/
configuration file. It will link a special header into the program.
That header will do the housekeeping that's needed by TGI.
An example command line:
<tscreen><verb>
cl65 -D DYN_DRV=0 -t vic20 -C vic20-tgi.cfg samples/mandelbrot.c
</verb></tscreen>
When the program starts, it will move itself up in RAM, to make room for the
buffer. When the program finishes, it will reset the BASIC interpreter.
That means that graphics pictures won't be preserved between the executions
of programs. Also, the graphics buffer shares RAM with the text screen. If
a picture must be saved, then a program must put it somewhere else (such as
a disk file) before returning to the text mode.
</descrip>
<sect1>Extended memory drivers<p>