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

Merge branch 'master' into seglist

Browse Source
This commit is contained in:
Bob Andrews
2025-07-03 23:16:51 +02:00
committed by GitHub
parent ad9e5cebbb 29f7ab3809
commit 3ae514921c
1009 changed files with 46517 additions and 9851 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/Makefile
View File

@@ -1,3 +1,9 @@
# ---- Display info during parsing phase ----
SILENT:=$(findstring s,$(word 1, $(MAKEFLAGS)))
ifneq ($(SILENT),s)
$(info Using Makefile: $(realpath $(firstword $(MAKEFILE_LIST))) $(MAKECMDGOALS))
endif
ifneq ($(shell echo),)
CMD_EXE = 1
endif

79
doc/agat.sgml Normal file
View File

@@ -0,0 +1,79 @@
<!doctype linuxdoc system>
<article>
<title>Agat-7/9 - specific information for cc65
<author><url url="https://sourceforge.net/u/olegodintsov/profile/" name="Oleg A. Odintsov">,<newline>
<url url="mailto:sintechs@gmail.com" name="Konstantin Fedorov">
<abstract>
An overview over the Agat-7 and Agat-9 and theirs interfaces to the cc65 C
compiler.
</abstract>
<!-- Table of contents -->
<toc>
<!-- Begin the document -->
<sect>Overview
<p>The Agat was a series of 8-bit computers produced in the Soviet Union from 1983 to 1993.
It was based on Apple II architecture with all electronic components made in the Soviet Union except for 6502 microprocessors supplied by UMC (UM6502A).
<p>If compared to Apple II, Agat had many improvements such as color text mode, additional graphic modes and flexible memory controller.
Agat-7 had an Apple II compatibility card called "Module 121", while Agat-9 had a built-in Apple II+ mode activated by soft-switch.
<p>All mass-produced Agat models were disk-based systems, 2K ROM contained only basic machine language monitor and disassembler.
Agat-7 had 140K floppy-drive based on Apple DISK II, while Agat-9 was supplied with 840K drive having its own sector format and controller.
<sect>Binary format<p>
The standard binary file format generated by the linker for the Agat target is
an AppleSingle file to be compatible with AppleCommander <url url="https://applecommander.github.io/">.
The default load address is &dollar;1903.
<sect>Platform-specific header files<p>
Programs containing Agat-specific code may use the <tt/agat.h/ or
<tt/agat.inc/ include files.
<sect>Usefull info<p>
<sect1>Emulation<p>
<enum>
<item> Oleg Odintsov's Agat Emulator - <url url="https://agatemulator.sourceforge.net/english.html">
<item> MAME - <url url="https://www.mamedev.org/">
</enum>
<sect1>Links<p>
<enum>
<item> Most informative source on Agat (in russian) - <url url="https://agatcomp.ru">
<item> Wikipedia - <url url="https://en.wikipedia.org/wiki/Agat_(computer)">
<item> Controversial article on Agat from <url name="BYTE Magazine November 1984 Vol. 9, No. 12" url="https://archive.org/details/byte-magazine-1984-11/page/n135/mode/2up?view=theater">.
The author reviewed custom-build mockup Agat bearing little relation to even the early Agat systems.
</enum>
<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>

98
doc/apple2.sgml
View File

@@ -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
@@ -87,12 +87,33 @@ several useful settings:
exit then a plain vanilla ProDOS 8 doesn't make use of the Language Card bank
2 at all.
<tag>LC address: &dollar;D000, LC size: &dollar;3000</tag>
<tag>LC address: &dollar;D000, LC size: &dollar;2FFC</tag>
For plain vanilla DOS 3.3 which doesn't make use of the Language Card at all.
</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>
@@ -289,9 +310,9 @@ the memory from &dollar;800 to &dollar;1FFF 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,6 +407,10 @@ 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.
@@ -434,10 +481,15 @@ The names in the parentheses denote the symbols to be used for static linking of
(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
@@ -569,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>
@@ -630,6 +704,16 @@ url="ca65.html" name="assembler manual">.
that can be used to set these variables. It is included in
<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>
A text file cannot be created with just the

73
doc/apple2enh.sgml
View File

@@ -63,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
@@ -88,7 +88,7 @@ several useful settings:
exit then a plain vanilla ProDOS 8 doesn't make use of the Language Card bank
2 at all.
<tag>LC address: &dollar;D000, LC size: &dollar;3000</tag>
<tag>LC address: &dollar;D000, LC size: &dollar;2FFC</tag>
For plain vanilla DOS 3.3 which doesn't make use of the Language Card at all.
</descrip><p>
@@ -290,9 +290,9 @@ the memory from &dollar;800 to &dollar;1FFF 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
@@ -322,15 +322,21 @@ 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>tgi_apple2_mix
@@ -339,6 +345,20 @@ usage.
</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>
<sect1>Hardware access<p>
There's currently no support for direct hardware access. This does not mean
@@ -435,10 +455,15 @@ The names in the parentheses denote the symbols to be used for static linking of
(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
@@ -575,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>
@@ -619,7 +666,7 @@ url="ca65.html" name="assembler manual">.
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()/
@@ -636,6 +683,16 @@ url="ca65.html" name="assembler manual">.
that can be used to set these variables. It is included in
<tt/apple2.h/, which is in turn included in <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>
A text file cannot be created with just the

7
doc/atari.sgml
View File

@@ -412,8 +412,9 @@ 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 necessary. A more memory
hungry solution consists in using the "<tt/posix_memalign()/" function in
conjunction with copying your data to the allocated 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>
@@ -1120,7 +1121,7 @@ If BSS and/or the stack shouldn't stay at the end of the program,
some parts of the cc65 runtime lib need to be replaced/modified.
common/_heap.s defines the location of the heap and atari/crt0.s
defines the location of the stack by initializing sp.
defines the location of the stack by initializing c_sp.
<sect1>Upgrading from an older cc65 version<p>

8
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 -->

753
doc/ca65.sgml
View File

File diff suppressed because it is too large Load Diff

12
doc/cc65-intern.sgml
View File

@@ -131,7 +131,7 @@ All other parameters will be pushed to the C-stack from left to right.
The rightmost parameter will have the lowest address on the stack,
and multi-byte parameters will have their least significant byte at the lower address.
The <tt/sp/ pseudo-register is a zeropage pointer to the base of the C-stack.
The <tt/c_sp/ pseudo-register is a zeropage pointer to the base of the C-stack.
If the function is variadic, the <tt/Y/ register will contain the number of
bytes pushed to the stack for this function.
@@ -153,10 +153,10 @@ void cdecl foo(unsigned bar, unsigned char baz);
; Example code for accessing bar. The variable is in A/X after this code snippet:
;
ldy #2 ; Offset of high byte of bar
lda (sp),y ; High byte now in A
lda (c_sp),y ; High byte now in A
tax ; High byte now in X
dey ; Offset of low byte of bar
lda (sp),y ; Low byte now in A
lda (c_sp),y ; Low byte now in A
</verb></tscreen>
<sect1>Epilogue, after the function call<p>
@@ -175,12 +175,12 @@ used if the return type is 32-bit.
If the function has a void return type, the compiler will not depend on the result
of <tt>A/X/sreg</tt>, so these may be clobbered by the function.
The C-stack pointer <tt/sp/ must be restored by the function to its value before the
The C-stack pointer <tt/c_sp/ must be restored by the function to its value before the
function call prologue. It may pop all of its parameters from the C-stack
(e.g. using the <tt/runtime/ function <tt/popa/),
or it could adjust <tt/sp/ directly.
or it could adjust <tt/c_sp/ directly.
If the function is variadic, the <tt/Y/ register contains the number of bytes
pushed to the stack on entry, which may be added to <tt/sp/ to restore its
pushed to the stack on entry, which may be added to <tt/c_sp/ to restore its
original state.
The internal pseudo-register <tt/regbank/ must not be changed by the function.

204
doc/cc65.sgml
View File

@@ -61,8 +61,10 @@ 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
-dM Output all user macros (needs -E)
-dP Output all predefined macros (needs -E)
-g Add debug info to object file
-h Help (this text)
-j Default characters are signed
@@ -84,8 +86,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
@@ -198,6 +201,28 @@ Here is a description of all the command line options:
Enables debug mode, for debugging the behavior of cc65.
<label id="option-dM">
<tag><tt>-dM</tt></tag>
When used with -E, will output <tt>#define</tt> directives for all the user
macros defined during execution of the preprocessor. This does not include
macros defined by the compiler.
Note: Can be combined with <tt/<ref id="option-dP" name="-dP">/ by using
<tt/-dMP/.
<label id="option-dP">
<tag><tt>-dP</tt></tag>
When used with -E, will output <tt>#define</tt> directives for all the macros
defined by the compiler itself. This does not include any user defined macros.
Note: Can be combined with <tt/<ref id="option-dM" name="-dM">/ by using
<tt/-dMP/.
<tag><tt>--debug-tables name</tt></tag>
Writes symbol table information to a file, which includes details on structs, unions
@@ -585,27 +610,42 @@ Here is a description of all the command line options:
<itemize>
<item>none
<item>agat (a russian apple2 like computer)
<item>apple2
<item>apple2enh
<item>atari
<item>atari2600
<item>atari5200
<item>atari7800
<item>atarixl
<item>atmos
<item>bbc
<item>c16 (works also for the c116 with memory up to 32K)
<item>c64
<item>c65
<item>c128
<item>cbm510 (CBM-II series with 40 column video)
<item>cbm610 (all CBM-II II computers with 80 column video)
<item>creativision
<item>cx16
<item>gamate
<item>geos-apple
<item>geos-cbm
<item>geos (alias for geos-cbm)
<item>kim1
<item>lunix
<item>lynx
<item>mega65
<item>nes
<item>osic1p
<item>pce (PC engine)
<item>pet (all CBM PET systems except the 2001)
<item>plus4
<item>p6502
<item>sim6502
<item>sim65c02
<item>supervision
<item>sym1
<item>telestrat
<item>vic20
</itemize>
@@ -823,6 +863,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
@@ -1047,6 +1092,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>
@@ -1138,6 +1193,134 @@ The compiler defines several macros at startup:
<item><tt/__CC65_STD_CC65__/
</itemize>
<label id="macro-CPU">
<tag><tt>__CPU__</tt></tag>
This macro contains a bitset that allows to check if a specific instruction
set is supported. For example, the 65C02 CPU supports all instructions of the
65SC02. So testing for the instruction set of the 65SC02 using the following
check will succeed for both CPUs (and also for the 65816 and HUC6280).
<tscreen><verb>
#if (__CPU__ & __CPU_ISET_65SC02__)
</verb></tscreen>
This is much simpler and more future proof than checking for specific CPUs.
The compiler defines a set of constants named <tt/__CPU_ISET_xxx/ to do the
checks. The <tt/__CPU__/ variable is usually derived from the target system
given, but can be changed using the <tt/<ref id="option--cpu" name="--cpu">/
command line option.
<tag><tt>__CPU_4510__</tt></tag>
This macro is defined if the code is compiled for a 4510 CPU.
<tag><tt>__CPU_45GS02__</tt></tag>
This macro is defined if the code is compiled for a 45GS02 CPU.
<tag><tt>__CPU_6502__</tt></tag>
This macro is defined if the code is compiled for a 6502 CPU.
<tag><tt>__CPU_6502X__</tt></tag>
This macro is defined if the code is compiled for a 6502 CPU with invalid
opcodes.
<tag><tt>__CPU_6502DTV__</tt></tag>
This macro is defined if the code is compiled for a DTV CPU.
<tag><tt>__CPU_65SC02__</tt></tag>
This macro is defined if the code is compiled for a 65SC02 CPU.
<tag><tt>__CPU_65C02__</tt></tag>
This macro is defined if the code is compiled for a 65C02 CPU.
<tag><tt>__CPU_65CE02__</tt></tag>
This macro is defined if the code is compiled for a 65CE02 CPU.
<tag><tt>__CPU_65816__</tt></tag>
This macro is defined if the code is compiled for a 65816 CPU.
<tag><tt>__CPU_HUC6280__</tt></tag>
This macro is defined if the code is compiled for a HUC6280 CPU.
<tag><tt>__CPU_M740__</tt></tag>
This macro is defined if the code is compiled for a M740 CPU.
<tag><tt>__CPU_W65C02__</tt></tag>
This macro is defined if the code is compiled for a W65C02 CPU.
<tag><tt>__CPU_ISET_6502__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the 6502 CPU.
<tag><tt>__CPU_ISET_6502X__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the 6502X CPU.
<tag><tt>__CPU_ISET_6502DTV__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the 6502DTV CPU.
<tag><tt>__CPU_ISET_65SC02__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the 65SC02 CPU.
<tag><tt>__CPU_ISET_65C02__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the 65C02 CPU.
<tag><tt>__CPU_ISET_65CE02__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the 65CE02 CPU.
<tag><tt>__CPU_ISET_65816__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the 65816 CPU.
<tag><tt>__CPU_ISET_HUC6280__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the HUC6280 CPU.
<tag><tt>__CPU_ISET_M740__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the M740 CPU.
<tag><tt>__CPU_ISET_W65C02__</tt></tag>
This macro expands to a numeric constant that can be used to check the
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the W65C02 CPU.
<tag><tt>__CX16__</tt></tag>
This macro is defined if the target is the Commander X16 (-t cx16).
@@ -1273,6 +1456,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>
@@ -1358,7 +1547,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>
@@ -1613,13 +1802,13 @@ 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/. If the identifier
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
@@ -1629,6 +1818,11 @@ parameter with the <tt/#pragma/.
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.

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.

3
doc/cl65.sgml
View File

@@ -261,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>

1082
doc/cpus.sgml Normal file
View File

File diff suppressed because it is too large Load Diff

6
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>
@@ -193,9 +193,9 @@ _init: LDX #$FF ; Initialize stack pointer to $01FF
; Set cc65 argument stack pointer
LDA #&lt;(__RAM_START__ + __RAM_SIZE__)
STA sp
STA c_sp
LDA #&gt;(__RAM_START__ + __RAM_SIZE__)
STA sp+1
STA c_sp+1
; ---------------------------------------------------------------------------
; Initialize memory storage

6
doc/cx16.sgml
View File

@@ -243,6 +243,12 @@ point to <tt/cx320p1.tgi (cx320p1_tgi)/.
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>

115
doc/da65.sgml
View File

@@ -46,14 +46,16 @@ The assembler accepts the following options:
---------------------------------------------------------------------------
Usage: da65 [options] [inputfile]
Short options:
-d Debug mode
-g Add debug info to object file
-h Help (this text)
-i name Specify an info file
-m Run multiple passes to resolve labels
-o name Name the output file
-v Increase verbosity
-F Add formfeeds to the output
-s Accept line markers in the info file
-S addr Set the start/load address
-s Accept line markers in the info file
-V Print the disassembler version
Long options:
@@ -61,6 +63,7 @@ Long options:
--comment-column n Specify comment start column
--comments n Set the comment level for the output
--cpu type Set cpu type
--debug Debug mode
--debug-info Add debug info to object file
--formfeeds Add formfeeds to the output
--help Help (this text)
@@ -68,6 +71,7 @@ Long options:
--info name Specify an info file
--label-break n Add newline if label exceeds length n
--mnemonic-column n Specify mnemonic start column
--multi-pass Run multiple passes to resolve labels
--pagelength n Set the page length for the listing
--start-addr addr Set the start/load address
--sync-lines Accept line markers in the info file
@@ -110,19 +114,23 @@ Here is a description of all the command line options:
Set the CPU type. The option takes a parameter, which may be one of
<itemize>
<item>6502
<item>6502x
<item>6502dtv
<item>65sc02
<item>65c02
<item>65816
<item>huc6280
<item>4510
<item>6502 - NMOS 6502 (all legal instructions)
<item>6502X - NMOS 6502 with all undocumented instructions
<item>6502DTV - the emulated CPU of the C64DTV device
<item>65SC02 - first CMOS instruction set (no bit manipulation, no wai/stp)
<item>65C02 - full CMOS instruction set (has bit manipulation and wai/stp)
<item>65816 - the CPU of the SNES, and the SCPU
<item>HuC6280 - the CPU of the PC engine
<item>4510 - the CPU of the Commodore C65
<item>45GS02 - the CPU of the Commodore MEGA65
<item>M740 - a Microcontroller by Mitsubishi
</itemize>
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.
<tag><tt>-d, --debug</tt></tag>
Enables debug mode, something that should not be needed for mere
mortals:-)
<label id="option--formfeeds">
@@ -181,6 +189,15 @@ Here is a description of all the command line options:
<tt><ref id="LABELBREAK" name="LABELBREAK"></tt>.
<tag><tt>-m, --multi-pass</tt></tag>
This option causes the disassembler to run multiple passes over the input
binary to find and create all necessary labels. Without this option the
disassembler may detect the necessity for a label in the final pass, when
output was already partially generated. It will output numerical addresses
or program counter relative expressions in this case.
<label id="option--mnemonic-column">
<tag><tt>--mnemonic-column n</tt></tag>
@@ -246,23 +263,85 @@ Here is a description of all the command line options:
<sect1>Supported CPUs<p>
With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
disassembler may be told which CPU to support:
<itemize>
<item>6502 - NMOS 6502 (all legal instructions)
<item>6502X - NMOS 6502 with all undocumented instructions
<item>6502DTV - the emulated CPU of the C64DTV device
<item>65SC02 - first CMOS instruction set (no bit manipulation, no wai/stp)
<item>65C02 - CMOS with Rockwell extensions
<item>W65C02 - full CMOS instruction set (has bit manipulation and wai/stp)
<item>65CE02 - CMOS with CSG extensions
<item>4510 - the CPU of the Commodore C65
<item>45GS02 - the CPU of the Commodore MEGA65
<item>HuC6280 - the CPU of the PC engine
<item>M740 - a Microcontroller by Mitsubishi
<item>65816 - the CPU of the SNES, and the SCPU
</itemize>
for more details on the various CPUs, see <tt><htmlurl url="cpus.html" name="here"></tt>.
<sect2>6502 mode<label id="6502-mode"><p>
The default (no CPU given on the command line or in the <tt/GLOBAL/ section of
the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
for this CPU. Invalid opcodes are translated into <tt/.byte/ commands.
With the command line option <tt><ref id="option--cpu" name="--cpu"></tt>, the
disassembler may be told to recognize either the 65SC02 or 65C02 CPUs. The
latter understands the same opcodes as the former, plus 16 additional bit
manipulation and bit test-and-branch commands. Using 6502x as CPU the illegal
opcodes of 6502 CPU are detected and displayed. 6502dtv setting recognizes the
emulated CPU instructons of the C64DTV device.
<sect2>6502X mode<label id="6502X-mode"><p>
Using 6502X as CPU the illegal opcodes of 6502 CPU are detected and displayed.
<sect2>DTV mode<label id="DTV-mode"><p>
6502DTV setting recognizes the emulated CPU instructions of the C64DTV device.
<sect2>65SC02 mode<label id="65SC02-mode"><p>
The first CMOS instruction set, without bit manipulation or wai/stp.
<sect2>65C02 mode<label id="65C02-mode"><p>
The 65C02 understands the same opcodes as the 65SC02, plus 16 additional bit
manipulation and bit test-and-branch commands.
<sect2>W65C02 mode<label id="W65C02-mode"><p>
This mode also supports wai/stp.
<sect2>65CE02 mode<label id="65CE02-mode"><p>
<sect2>4510 mode<label id="4510-mode"><p>
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.
<sect2>45GS02 mode<label id="45GS02-mode"><p>
All compound instructions are supported.
<sect2>HUC6280 mode<label id="HUC6280-mode"><p>
All special opcodes are supported.
<sect2>M740 mode<label id="M740-mode"><p>
All special opcodes are supported.
<sect2>65816 mode<label id="65816-mode"><p><p>
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.

561
doc/funcref.sgml
View File

@@ -71,18 +71,21 @@ function.
<item><ref id="detect_c64dtv" name="detect_c64dtv">
<item><ref id="detect_c65" name="detect_c65">
<item><ref id="detect_chameleon" name="detect_chameleon">
<item><ref id="detect_iigs" name="detect_iigs">
<item><ref id="detect_scpu" name="detect_scpu">
<item><ref id="detect_turbomaster" name="detect_turbomaster">
<item><ref id="get_c128_speed" name="get_c128_speed">
<item><ref id="get_c64dtv_speed" name="get_c64dtv_speed">
<item><ref id="get_c65_speed" name="get_c65_speed">
<item><ref id="get_chameleon_speed" name="get_chameleon_speed">
<item><ref id="get_iigs_speed" name="get_iigs_speed">
<item><ref id="get_scpu_speed" name="get_scpu_speed">
<item><ref id="get_turbomaster_speed" name="get_turbomaster_speed">
<item><ref id="set_c128_speed" name="set_c128_speed">
<item><ref id="set_c64dtv_speed" name="set_c64dtv_speed">
<item><ref id="set_c65_speed" name="set_c65_speed">
<item><ref id="set_chameleon_speed" name="set_chameleon_speed">
<item><ref id="set_iigs_speed" name="set_iigs_speed">
<item><ref id="set_scpu_speed" name="set_scpu_speed">
<item><ref id="set_turbomaster_speed" name="set_turbomaster_speed">
</itemize>
@@ -92,8 +95,16 @@ function.
<itemize>
<item>_dos_type
<item>allow_lowercase
<item><ref id="beep" name="beep">
<item><ref id="dir_entry_count" name="dir_entry_count">
<item><ref id="get_tv" name="get_tv">
<item><ref id="get_ostype" name="get_ostype">
<item><ref id="gmtime_dt" name="gmtime_dt">
<item><ref id="mktime_dt" name="mktime_dt">
<item>rebootafterexit
<item><ref id="videomode" name="videomode">
<item><ref id="waitvsync" name="waitvsync">
</itemize>
@@ -101,9 +112,15 @@ function.
<itemize>
<item>_dos_type
<item><ref id="beep" name="beep">
<item><ref id="dir_entry_count" name="dir_entry_count">
<item><ref id="get_tv" name="get_tv">
<item><ref id="get_ostype" name="get_ostype">
<item><ref id="gmtime_dt" name="gmtime_dt">
<item><ref id="mktime_dt" name="mktime_dt">
<item>rebootafterexit
<item><ref id="videomode" name="videomode">
<item><ref id="waitvsync" name="waitvsync">
</itemize>
@@ -128,7 +145,7 @@ function.
<!-- <item><ref id="_setcolor_low" name="_setcolor_low"> -->
<item><ref id="_sound" name="_sound">
<item><ref id="get_ostype" name="get_ostype">
<!-- <item><ref id="get_tv" name="get_tv"> -->
<item><ref id="get_tv" name="get_tv">
</itemize>
(incomplete)
@@ -145,6 +162,7 @@ function.
<item><ref id="atmos_tick" name="atmos_tick">
<item><ref id="atmos_tock" name="atmos_tock">
<item><ref id="atmos_zap" name="atmos_zap">
<item><ref id="waitvsync" name="waitvsync">
</itemize>
@@ -214,7 +232,7 @@ function.
<!-- <item><ref id="cbm_readdir" name="cbm_readdir"> -->
<!-- <item><ref id="cbm_save" name="cbm_save"> -->
<!-- <item><ref id="cbm_write" name="cbm_write"> -->
<!-- <item><ref id="get_tv" name="get_tv"> -->
<item><ref id="get_tv" name="get_tv">
<item><ref id="kbrepeat" name="kbrepeat">
<item><ref id="waitvsync" name="waitvsync">
</itemize>
@@ -271,6 +289,7 @@ function.
<item><ref id="cclear" name="cclear">
<item><ref id="cclearxy" name="cclearxy">
<item><ref id="cgetc" name="cgetc">
<item><ref id="cgets" name="cgets">
<item><ref id="chline" name="chline">
<item><ref id="chlinexy" name="chlinexy">
<item><ref id="clrscr" name="clrscr">
@@ -283,6 +302,7 @@ function.
<item><ref id="cputcxy" name="cputcxy">
<item><ref id="cputs" name="cputs">
<item><ref id="cputsxy" name="cputsxy">
<item><ref id="cscanf" name="cscanf">
<item><ref id="cursor" name="cursor">
<item><ref id="cvline" name="cvline">
<item><ref id="cvlinexy" name="cvlinexy">
@@ -335,7 +355,7 @@ function.
<itemize>
<!-- <item><ref id="get_numbanks" name="get_numbanks"> -->
<item><ref id="get_ostype" name="get_ostype">
<!-- <item><ref id="get_tv" name="get_tv"> -->
<item><ref id="get_tv" name="get_tv">
<!-- <item><ref id="set_tv" name="set_tv"> -->
<!-- <item><ref id="vera_layer_enable" name="vera_layer_enable"> -->
<!-- <item><ref id="vera_sprites_enable" name="vera_sprites_enable"> -->
@@ -430,7 +450,7 @@ see also <tt>testcode/lib/em-test.c</tt> and <tt>samples/multidemo.c</tt>.
<sect1><tt/gamate.h/<label id="gamate.h"><p>
<itemize>
<!-- <item><ref id="get_tv" name="get_tv"> -->
<item><ref id="get_tv" name="get_tv">
<item><ref id="waitvsync" name="waitvsync">
</itemize>
@@ -506,6 +526,14 @@ see also <tt>testcode/lib/em-test.c</tt> and <tt>samples/multidemo.c</tt>.
</itemize>
<sect1><tt/lzsa.h/<label id="lzsa.h"><p>
<itemize>
<item><ref id="decompress_lzsa1" name="decompress_lzsa1">
<item><ref id="decompress_lzsa2" name="decompress_lzsa2">
</itemize>
<sect1><tt/modload.h/<label id="modload.h"><p>
<itemize>
@@ -537,7 +565,7 @@ see also <tt>testcode/lib/em-test.c</tt> and <tt>samples/multidemo.c</tt>.
<sect1><tt/nes.h/<label id="nes.h"><p>
<itemize>
<!-- <item><ref id="get_tv" name="get_tv"> -->
<item><ref id="get_tv" name="get_tv">
<item><ref id="waitvsync" name="waitvsync">
</itemize>
@@ -555,7 +583,7 @@ It does not declare any functions.
<sect1><tt/pce.h/<label id="pce.h"><p>
<itemize>
<!-- <item><ref id="get_tv" name="get_tv"> -->
<item><ref id="get_tv" name="get_tv">
<item><ref id="waitvsync" name="waitvsync">
</itemize>
@@ -725,7 +753,7 @@ communication, see also <tt>testcode/lib/ser-test.c</tt>.
<item><ref id="ltoa" name="ltoa">
<item><ref id="malloc" name="malloc">
<item><ref id="perror" name="perror">
<!-- <item><ref id="posix_memalign" name="posix_memalign"> -->
<item><ref id="posix_memalign" name="posix_memalign">
<!-- <item><ref id="putenv" name="putenv"> -->
<item><ref id="qsort" name="qsort">
<item><ref id="rand" name="rand">
@@ -771,6 +799,7 @@ communication, see also <tt>testcode/lib/ser-test.c</tt>.
<item><ref id="strqtok" name="strqtok">
<item><ref id="strrchr" name="strrchr">
<item><ref id="strspn" name="strspn">
<item><ref id="strcasestr" name="strcasestr">
<item><ref id="strstr" name="strstr">
<item><ref id="strtok" name="strtok">
<item><ref id="strxfrm" name="strxfrm">
@@ -846,6 +875,20 @@ communication, see also <tt>testcode/lib/ser-test.c</tt>.
(incomplete)
<sect1><tt/stat.h/<label id="sys/stat.h"><p>
<itemize>
<item><ref id="stat" name="stat">
</itemize>
<sect1><tt/statvfs.h/<label id="sys/statvfs.h"><p>
<itemize>
<item><ref id="statvfs" name="statvfs">
</itemize>
<sect1><tt/vic20.h/<label id="vic20.h"><p>
(incomplete)
@@ -863,6 +906,13 @@ communication, see also <tt>testcode/lib/ser-test.c</tt>.
(incomplete)
<sect1><tt/zx02.h/<label id="zx02.h"><p>
<itemize>
<item><ref id="decompress_zx02" name="decompress_zx02">
</itemize>
<sect>Alphabetical function reference<p>
<sect1>_DE_ISDIR<label id="_DE_ISDIR"><p>
@@ -1750,10 +1800,11 @@ used in presence of a prototype.
<descrip>
<tag/Function/Beep sound.
<tag/Header/<tt/<ref id="sym1.h" name="sym1.h">/
<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">/
<tag/Declaration/<tt/void beep(void);/
<tag/Description/<tt/beep/ makes a brief tone.
<tag/Notes/<itemize>
<item>The function is specific to the Sym-1.
<item>The function is specific to the Sym-1 and Apple2 platforms.
</itemize>
<tag/Availability/cc65
<tag/See also/
@@ -2407,7 +2458,7 @@ the address must first be ORed with $60.
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_listen" name="cbm_k_listen">
<tag/Exampe/None.
<tag/Example/None.
</descrip>
</quote>
@@ -2666,6 +2717,45 @@ see anything that you type. (See the description of <tt/cbm_k_scnkey()/.)
</quote>
<sect1>cgets<label id="cgets"><p>
<quote>
<descrip>
<tag/Function/Input a string directly from the console.
<tag/Header/<tt/<ref id="conio.h" name="conio.h">/
<tag/Declaration/<tt/char* __fastcall__ cgets (const char* buffer, int size);/
<tag/Description/The function inputs a string of at most <tt/size - 1/
characters from the console into <tt/buffer/. It returns when <tt/size - 1/
characters or either <tt/CR/ or <tt/LF/ are entered. It also handles both
multi-line input and backspacing.
<tag/Notes/<itemize>
<item>The function echoes <tt/CRLF/ when either <tt/CR/ or <tt/LF/ are read
but does NOT append either in <tt/buffer/.
<item>The function is only available as fastcall function, so it may only
be used in the presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cgetc" name="cgetc">,
<ref id="cscanf" name="cscanf">
<tag/Example/<verb>
#include &lt;conio.h&gt;
int main (void)
{
char buffer[200], *p;
cputs ("Type a lot and backspace a lot: ");
if (p = cgets (buffer, sizeof(buffer)))
cputs (p);
return 0;
}
</verb>
</descrip>
</quote>
<sect1>chline<label id="chline"><p>
<quote>
@@ -2851,6 +2941,79 @@ setting the time may not work. See also the platform-specific information.
</quote>
<sect1>gmtime_dt<label id="gmtime_dt"><p>
<quote>
<descrip>
<tag/Function/Converts a ProDOS date to a struct tm.
<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">/
<tag/Declaration/<tt/struct tm* __fastcall__ gmtime_dt (const struct datetime* dt);/
<tag/Description/The <tt/gmtime_dt/ function converts the given
proDOS date/time to a struct tm. On error, NULL is returned and <tt/errno/ is set
to an error code describing the reason for the failure.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
<item>This function is only available on Apple II.
<item>On Apple II, you can't stat() an opened file. stat() before opening.
</itemize>
<tag/Availability/cc65
<tag/Example/
<verb>
#include <stdio.h>
#include <time.h>
#include <sys/stat.h>
int main(void)
{
struct stat st;
struct tm* tm;
if (stat ("/disk/file", &amp;st) == 0) {
tm = gmtime_dt (&amp;st.st_ctime);
if (tm)
printf ("File created on %s\n", asctime(tm));
}
}
</verb>
</descrip>
</quote>
<sect1>mktime_dt<label id="mktime_dt"><p>
<quote>
<descrip>
<tag/Function/Converts a ProDOS date to a time_t.
<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">/
<tag/Declaration/<tt/time_t __fastcall__ mktime_dt (const struct datetime* dt);/
<tag/Description/The <tt/mktime_dt/ function parses the given
proDOS date/time and returns a time_t timestamp. On error, 0 is returned,
and errno is set.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
<item>This function is only available on Apple II.
</itemize>
<tag/Availability/cc65
<tag/Example/
<verb>
#include <stdio.h>
#include <time.h>
#include <sys/stat.h>
int main(void)
{
struct stat st;
if (stat ("/disk/file", &amp;st) == 0) {
printf ("File created on %s\n",
localtime (mktime_dt (&amp;st.st_ctime)));
}
}
</verb>
</descrip>
</quote>
<sect1>clrscr<label id="clrscr"><p>
<quote>
@@ -3192,6 +3355,47 @@ be used in presence of a prototype.
</quote>
<sect1>cscanf<label id="cscanf"><p>
<quote>
<descrip>
<tag/Function/Read formatted input from the console
<tag/Header/<tt/<ref id="conio.h" name="conio.h">/
<tag/Declaration/<tt/int cscanf (const char* format, ...);/
<tag/Description/The <tt/cscanf()/ function scans input from the console under
control of the argument <tt/format/. Following the format string is a list of
addresses to receive values. The format string is identical to that of the
<tt/scanf()/ function.
<tag/Notes/<itemize>
<item>A direct call to <tt/cursor()/ may be required to show the cursor.
<item>Some control characters like backspaces are not recognized.
<item>A better user experience can sometimes be provided by using <tt/cgets()/
to retrieve the input, and then using <tt/sscanf()/ to parse it.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cgets" name="cgets">,
<ref id="cursor" name="cursor">
<tag/Example/<verb>
#include &lt;conio.h&gt;
int main (void)
{
int a, b, c;
cputs ("Type three integers that add to 100: ");
if (cscanf ("%d %d %d", &amp;a, &amp;b, &amp;c) == 3 && a + b + c == 100)
cputs ("\r\nYou passed!\r\n");
else
cputs ("\r\nYou failed!\r\n");
return 0;
}
</verb>
</descrip>
</quote>
<sect1>cursor<label id="cursor"><p>
<quote>
@@ -3277,6 +3481,70 @@ used in presence of a prototype.
<tag/Description/<tt/decompress_lz4/ uncompresses a LZ4-compressed buffer.
<tag/Notes/<itemize>
<item>Use LZ4_compress_HC with compression level 16 for best compression.
<item>Your program will need to know the uncompressed size of the buffer as
there is no end-of-stream marker.
<item>LZ4 is the biggest and second-slowest decompressor shipped in cc65 runtime.
It is also the least efficient compression algorithm.
</itemize>
<tag/Availability/cc65
<tag/Example/None.
</descrip>
</quote>
<sect1>decompress_lzsa1<label id="decompress_lzsa1"><p>
<quote>
<descrip>
<tag/Function/Uncompress a LZSA buffer with format 1.
<tag/Header/<tt/<ref id="lzsa.h" name="lzsa.h">/
<tag/Declaration/<tt/void decompress_lzsa1 (const unsigned char* src, unsigned char* const dst);/
<tag/Description/<tt/decompress_lz4/ uncompresses a LZSA buffer with format 1.
<tag/Notes/<itemize>
<item>Use <tt/lzsa -f 1 -r input.bin output.lzsa1/ to compress your input.
<item>The project and compressor can be found at <url url="https://github.com/emmanuel-marty/lzsa">
<item>LZSA1 is the fastest decompressor shipped in cc65 runtime, but data is less
compressed than with LZSA2 and ZX02.
</itemize>
<tag/Availability/cc65
<tag/Example/None.
</descrip>
</quote>
<sect1>decompress_lzsa2<label id="decompress_lzsa2"><p>
<quote>
<descrip>
<tag/Function/Uncompress a LZSA buffer with format 2.
<tag/Header/<tt/<ref id="lzsa.h" name="lzsa.h">/
<tag/Declaration/<tt/void decompress_lzsa2 (const unsigned char* src, unsigned char* const dst);/
<tag/Description/<tt/decompress_lz4/ uncompresses a LZSA buffer with format 2.
<tag/Notes/<itemize>
<item>Use <tt/lzsa -f 2 -r input.bin output.lzsa2/ to compress your input.
<item>The project and compressor can be found at <url url="https://github.com/emmanuel-marty/lzsa">
<item>LZSA2 is the second fastest decompressor shipped in cc65 runtime, but data is less
compressed than with ZX02.
</itemize>
<tag/Availability/cc65
<tag/Example/None.
</descrip>
</quote>
<sect1>decompress_zx02<label id="decompress_zx02"><p>
<quote>
<descrip>
<tag/Function/Uncompress a ZX02 buffer.
<tag/Header/<tt/<ref id="zx02.h" name="zx02.h">/
<tag/Declaration/<tt/void decompress_zx02 (const unsigned char* src, unsigned char* const dst);/
<tag/Description/<tt/decompress_zx02/ uncompresses a ZX02 buffer with format 2.
<tag/Notes/<itemize>
<item>Use <tt/zx02 input.bin output.zx02/ to compress your input.
<item>The project and compressor can be found at <url url="https://github.com/dmsc/zx02">
<item>ZX02 is the slowest decompressor shipped with cc65 runtime, but is also the
smallest and has the best compression ratio.
</itemize>
<tag/Availability/cc65
<tag/Example/None.
@@ -3364,6 +3632,26 @@ used in presence of a prototype.
</quote>
<sect1>detect_iigs<label id="detect_iigs"><p>
<quote>
<descrip>
<tag/Function/Check whether we are running on an Apple IIgs..
<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
<tag/Declaration/<tt/unsigned char detect_iigs (void);/
<tag/Description/The function returns a 1 if running on an Apple IIgs.
<tag/Notes/<itemize>
<item>The function is specific to the Apple2 and Apple2enh platforms.
</itemize>
<tag/Availability/cc65 (not all platforms)
<tag/See also/
<ref id="get_iigs_speed" name="get_iigs_speed">,
<ref id="set_iigs_speed" name="set_iigs_speed">,
<tag/Example/None.
</descrip>
</quote>
<sect1>detect_scpu<label id="detect_scpu"><p>
<quote>
@@ -3404,6 +3692,25 @@ used in presence of a prototype.
</quote>
<sect1>dir_entry_count<label id="dir_entry_count"><p>
<quote>
<descrip>
<tag/Function/Returns the number of entries in the directory.
<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">/
<tag/Declaration/<tt/unsigned int __fastcall__ dir_entry_count(DIR *dir);/
<tag/Description/<tt/dir_entry_count/ is machine dependent and does not exist for
all supported targets. If it exists, it returns the number of active
(non-deleted) files and directories in the directory.
<tag/Notes/<itemize>
<item>The function does not exist on all platforms.
</itemize>
<tag/Availability/cc65 (not all platforms)
<tag/Example/None.
</descrip>
</quote>
<sect1>div<label id="div"><p>
<quote>
@@ -3967,6 +4274,31 @@ be used in presence of a prototype.
</quote>
<sect1>get_tv<label id="get_tv"><p>
<quote>
<descrip>
<tag/Function/The function returns the system's vertical blank frequency.
<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">,
<ref id="atari.h" name="atari.h">, <ref id="cbm.h" name="cbm.h">,
<ref id="cx16.h" name="cx16.h">, <ref id="gamate.h" name="gamate.h">,
<ref id="nes.h" name="nes.h">, <ref id="pce.h" name="pce.h">/
<tag/Declaration/<tt/unsigned char get_tv (void);/
<tag/Description/<tt/get_tv/ is machine dependent and does not exist for
all supported targets. If it exists, it returns a number that identifies the
frequency at which the screen vertical blank happens (either 50 or 60Hz),
if possible.
<tag/Notes/<itemize>
<item>The function does not exist on all platforms.
<item>Return TV_NTSC for 60Hz systems, TV_PAL for 50Hz systems, or
TV_OTHER if the scan frequency can not be determined.
</itemize>
<tag/Availability/cc65 (not all platforms)
<tag/Example/None.
</descrip>
</quote>
<sect1>get_ostype<label id="get_ostype"><p>
<quote>
@@ -4078,6 +4410,27 @@ header files define constants that can be used to check the return code.
</quote>
<sect1>get_iigs_speed<label id="get_iigs_speed"><p>
<quote>
<descrip>
<tag/Function/Get the current speed of the Apple IIgs.
<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
<tag/Declaration/<tt/unsigned char get_iigs_speed (void);/
<tag/Description/The function returns the current speed of the Apple IIgs.
<tag/Notes/<itemize>
<item>The function is specific to the Apple2 and Apple2enh platforms.
<item>See the accelerator.h header for the speed definitions.
</itemize>
<tag/Availability/cc65 (not all platforms)
<tag/See also/
<ref id="detect_iigs" name="detect_iigs">,
<ref id="set_iigs_speed" name="set_iigs_speed">,
<tag/Example/None.
</descrip>
</quote>
<sect1>get_scpu_speed<label id="get_scpu_speed"><p>
<quote>
@@ -6061,6 +6414,32 @@ be used in presence of a prototype.
</quote>
<sect1>posix_memalign<label id="posix_memalign"><p>
<quote>
<descrip>
<tag/Function/Allocate aligned dynamic memory.
<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/
<tag/Declaration/<tt/int __fastcall__ posix_memalign (void** memptr, size_t alignment, size_t size);/
<tag/Description/Allocate a block of memory with the given "size", which is aligned to a
memory address that is a multiple of "alignment". "alignment" <em/must not/ be
zero, and <em/must/ be a power of two; otherwise, this function will return
EINVAL. The function returns ENOMEM if not enough memory is available
to satisfy the request. "memptr" must point to a variable; that variable
will return the address of the allocated memory. Use free() to release that
allocated block.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
</itemize>
<tag/Availability/POSIX 1003.1
<tag/See also/
<ref id="free" name="free">
<tag/Example/None.
</descrip>
</quote>
<sect1>psg_delay<label id="psg_delay"><p>
<quote>
@@ -6229,6 +6608,9 @@ be used in presence of a prototype.
<item>The returned pointer may point to a statically allocated instance of
<tt/struct dirent/, so it may get overwritten by subsequent calls to
<tt/readdir/.
<item>On the Apple II platform, the d_ctime and d_mtime returned are in the
ProDOS format. You can convert them to more portable time representations using
the ProDOS datetime conversion functions.
<item>On several platforms, namely the CBMs and the Atari, the disk drives get
confused when opening/closing files between directory reads. So for example a
program that reads the list of files on a disk, and after each call to
@@ -6893,6 +7275,30 @@ clean-up when exiting the program.
</quote>
<sect1>set_iigs_speed<label id="set_iigs_speed"><p>
<quote>
<descrip>
<tag/Function/Set the current speed of the Apple IIgs.
<tag/Header/<tt/<ref id="accelerator.h" name="accelerator.h">/
<tag/Declaration/<tt/unsigned char __fastcall__ set_iigs_speed (unsigned char speed);/
<tag/Description/The function sets the speed of the Apple IIgs CPU (and returns
the new speed).
<tag/Notes/<itemize>
<item>The function is specific to the Apple2 and Apple2enh platforms.
<item>See the accelerator.h header for the speed definitions.
<item>Accepted parameters are SPEED_SLOW and SPEED_FAST (all other values are
considered SPEED_FAST).
</itemize>
<tag/Availability/cc65 (not all platforms)
<tag/See also/
<ref id="detect_iigs" name="detect_iigs">,
<ref id="get_iigs_speed" name="get_iigs_speed">,
<tag/Example/None.
</descrip>
</quote>
<sect1>set_scpu_speed<label id="set_scpu_speed"><p>
<quote>
@@ -7075,6 +7481,85 @@ be used in presence of a prototype.
</quote>
<sect1>stat<label id="stat"><p>
<quote>
<descrip>
<tag/Function/Get file status.
<tag/Header/<tt/<ref id="sys/stat.h" name="sys/stat.h">/
<tag/Declaration/<tt/int __fastcall__ stat (const char* pathname, struct stat* statbuf);/
<tag/Description/<tt/stat/ gets information for the file with the given name. On success,
zero is returned. On error, -1 is returned and <tt/errno/ is set to an error
code describing the reason for the failure.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
<item>On the Apple II platform, the st_ctim, st_mtim and st_atim members are left
to zero, for size and performance reasons. The ProDOS creation and modification dates
are returned in the ProDOS format in st_ctime and st_mtime. The access date does
not exist. You can convert them to POSIX-style time representations using
the <url url="apple2.html#ss9.3" name="ProDOS datetime conversion functions">.
</itemize>
<tag/Availability/POSIX 1003.1
<tag/See also/
<ref id="statvfs" name="statvfs">
<tag/Example/
<verb>
#include &lt;sys/stat.h&gt;
#define FILENAME "helloworld"
struct stat stbuf;
if (stat (FILENAME, &amp;stbuf) == 0) {
printf ("%s size is %lu bytes (created on %s)\n", FILENAME, stbuf.st_size,
#ifndef __APPLE2__
localtime (&amp;stbuf.st_ctim.tv_sec)
#else
localtime (mktime_dt (&amp;stbuf.st_ctime))
#endif
);
} else {
printf ("There was a problem stat'ing %s: %d\n", FILENAME, errno);
}
</verb>
</descrip>
</quote>
<sect1>statvfs<label id="statvfs"><p>
<quote>
<descrip>
<tag/Function/Get filesystem statistics.
<tag/Header/<tt/<ref id="sys/statvfs.h" name="sys/statvfs.h">/
<tag/Declaration/<tt/int __fastcall__ statvfs (const char* pathname, struct statvfs* buf);/
<tag/Description/<tt/statvfs/ gets information for the filesystem on which the given file
resides. On success,
zero is returned. On error, -1 is returned and <tt/errno/ is set to an error
code describing the reason for the failure.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
<item>The function requires an absolute pathname.
</itemize>
<tag/Availability/POSIX 1003.1
<tag/See also/
<ref id="stat" name="stat">
<tag/Example/
<verb>
#include &lt;sys/statvfs.h&gt;
#define FILENAME "/disk/helloworld"
struct statvfs stvbuf;
if (statvfs (FILENAME, &amp;stvbuf) == 0) {
printf ("%s filesystem has %u blocks of %u size, %u of them free.\n", FILENAME, stvbuf.f_blocks, stvbuf.f_bsize, stvbuf.f_bfree);
} else {
printf ("There was a problem statvfs'ing %s: %d\n", FILENAME, errno);
}
</verb>
</descrip>
</quote>
<sect1>strcasecmp<label id="strcasecmp"><p>
<quote>
@@ -7655,22 +8140,47 @@ be used in presence of a prototype.
</quote>
<sect1>strstr<label id="strstr"><p>
<sect1>strcasestr<label id="strcasestr"><p>
<quote>
<descrip>
<tag/Function/Find a substring.
<tag/Function/Find a substring, case-insensitive.
<tag/Header/<tt/<ref id="string.h" name="string.h">/
<tag/Declaration/<tt/char* __fastcall__ strstr (const char* str, const char* substr);/
<tag/Description/<tt/strstr/ searches for the first occurrence of the string
<tt/substr/ within <tt/str/. If found, it returns a pointer to the copy,
otherwise it returns <tt/NULL/.
<tag/Declaration/<tt/char* __fastcall__ strcasestr (const char* str, const char* substr);/
<tag/Description/<tt/strcasestr/ searches for the first occurrence of the string
<tt/substr/ within <tt/str/. If found, it returns a pointer to the start of the
match in <tt/str/, otherwise it returns <tt/NULL/.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
</itemize>
<tag/Availability/ISO 9899
<tag/See also/
<ref id="strstr" name="strstr">,
<ref id="strcspn" name="strcspn">,
<ref id="strspn" name="strspn">
<tag/Example/None.
</descrip>
</quote>
<sect1>strstr<label id="strstr"><p>
<quote>
<descrip>
<tag/Function/Find a substring, case-sensitive.
<tag/Header/<tt/<ref id="string.h" name="string.h">/
<tag/Declaration/<tt/char* __fastcall__ strstr (const char* str, const char* substr);/
<tag/Description/<tt/strstr/ searches for the first occurrence of the string
<tt/substr/ within <tt/str/. If found, it returns a pointer to the start of the
match in <tt/str/, otherwise it returns <tt/NULL/.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
</itemize>
<tag/Availability/ISO 9899
<tag/See also/
<ref id="strcasestr" name="strcasestr">,
<ref id="strcspn" name="strcspn">,
<ref id="strspn" name="strspn">
<tag/Example/None.
@@ -8052,24 +8562,27 @@ used in presence of a prototype.
<tag/Function/Switch to either 40- or 80-column text mode, or a standard
graphics mode.
<tag/Header/<tt/
<ref id="apple2.h" name="apple2.h">,
<ref id="apple2enh.h" name="apple2enh.h">,
<ref id="c128.h" name="c128.h">,
<ref id="cx16.h" name="cx16.h">/
<tag/Declaration/
<tt>unsigned __fastcall__ videomode (unsigned Mode); /* for apple2enh and c128 */</tt><newline>
<tt>signed char __fastcall__ videomode (signed char Mode); /* for cx16 */</tt>
<tt>unsigned __fastcall__ videomode (unsigned Mode); /* for c128 */</tt><newline>
<tt>signed char __fastcall__ videomode (signed char Mode); /* for apple2 and cx16 */</tt>
<tag/Description/Switch to a 40- or 80-column text or graphics mode, depending
on the argument. If the requested mode is already active, nothing happens. The
old mode is returned from the call.
<tag/Notes/<itemize>
<item>The function is specific to the Commodore 128, the enhanced Apple //e,
<item>The function is specific to the Commodore 128, the Apple II,
and the Commander X16.
<item>This function replaces <ref id="toggle_videomode"
name="toggle_videomode">.
<item>The function is available as only a fastcall function, so it may be used
only in the presence of a prototype.
<item>On Apple II, this functions returns the previously active video mode, or -1
if the mode is not supported due to lack of hardware.
</itemize>
<tag/Availability/C128, enhanced Apple //e, and CX16
<tag/Availability/C128, Apple II, and CX16
<tag/See also/
<ref id="fast" name="fast">,
<ref id="isfast" name="isfast">,
@@ -8087,13 +8600,21 @@ only in the presence of a prototype.
<descrip>
<tag/Function/Wait until the start of the next video frame.
<tag/Header/<tt/
<ref id="apple2.h" name="apple2.h">,
<ref id="atmos.h" name="atmos.h">,
<ref id="cbm.h" name="cbm.h">,
<ref id="gamate.h" name="gamate.h">,
<ref id="nes.h" name="nes.h">,
<ref id="pce.h" name="pce.h">/
<tag/Declaration/<tt/void waitvsync (void);/
<tag/Declaration/
<tt>void waitvsync (void);</tt><newline>
<tag/Description/Wait for vertical sync, to reduce flickering.
<tag/Notes/<itemize>
<item>The function will silently fail when the feature is not
supported, like on the Apple&nbsp;&rsqb;&lsqb;+.
</itemize>
<tag/Availability/Platforms served by the headers above
(Atmos requires the VSync hack)
<tag/Example/None.
</descrip>
</quote>

3
doc/index.sgml
View File

@@ -109,6 +109,9 @@
<descrip>
<tag><htmlurl url="agat.html" name="agat.html"></tag>
Topics specific to the Agat machines.
<tag><htmlurl url="apple2.html" name="apple2.html"></tag>
Topics specific to the Apple&nbsp;&rsqb;&lsqb;.

196
doc/ld65.sgml
View File

@@ -1180,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>

20
doc/plus4.sgml
View File

@@ -165,8 +165,26 @@ 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 Plus/4.
<descrip>
<tag><tt/ted-hi.tgi (ted_hi_tgi)/</tag>
This driver features a resolution of 320*200 with two colors and an
adjustable palette (that means that the two colors can be chosen out of a
palette of the 121 TED colors).
Note that the text-mode character matrix and color data are destroyed by this
driver. The driver calls the Kernal <tt/CLRSCR/ routine to return the text
screen to a usable (if empty) state on <tt/tgi_done()/.
This driver places the bitmap at &dollar;C000-&dollar;E000. Programs using
this driver must either be linked with the option <tt/-D
__HIMEM__=&dollar;C000/, or use the <tt/plus4-hires.cfg/ linker configuration.
The <tt/plus4-hires.cfg/ is preferable, as it allows the stack to remain at
&dollar;FCFF, and exposes the remaining high memory from the end of the bitmap
to the stack top as a <tt/HIBSS/ segment that can be used by the programmer,
or given to <tt/_heapadd()/ (using the symbols <tt/_HIBSS_START__/ and
<tt/_HIBSS_SIZE__/).
</descrip><p>
<sect1>Extended memory drivers<p>

272
doc/sim65.sgml
View File

@@ -40,6 +40,8 @@ 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>
@@ -70,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.
@@ -115,37 +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.
The <tt/stdlib.h/ <tt/exit/ function may also be used to terminate with an exit code.
Exit codes are limited to 8 bits.
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/.
Define and export <tt/_main/ as an entry point,
Though a C test may also link with assembly code,
a pure assembly test can also be created.
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/.
<item><tt/jmp exit/ with the code in <tt/A/. (<tt/.import exit/ from the sim65 library.)
</itemize>
The binary file has a 12 byte header:
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>
@@ -155,7 +209,7 @@ The binary file has a 12 byte header:
<item>1 byte <bf/CPU type/: <tt/0/ = 6502, <tt/1/ = 65C02
<item>1 byte <bf/sp address/: the zero page address of the C parameter stack pointer <tt/sp/ used by the paravirtualization functions
<item>1 byte <bf/c_sp address/: the zero page address of the C parameter stack pointer <tt/c_sp/ used by the paravirtualization functions
<item>1 word <bf/load address/: where to load the data from the file into memory (default: <tt/$0200/)
@@ -182,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>

66
doc/tgi.sgml
View File

@@ -43,7 +43,7 @@ of range.
<ref id="tgi_setcolor" name="tgi_setcolor">
<tag/Example/<tscreen><verb>
/* Draw the upper half of an ellipse */
tgi_setcolor(TGI_COLOR_BLUE);
tgi_setcolor(1);
tgi_arc (50, 50, 40, 20, 0, 180);
</verb></tscreen>
</descrip>
@@ -67,7 +67,7 @@ be used in presence of a prototype.
<tag/Availability/cc65
<tag/See also/Other tgi function
<tag/Example/<tscreen><verb>
tgi_setcolor(TGI_COLOR_GREEN);
tgi_setcolor(1);
tgi_bar(10, 10, 100, 60);
</verb></tscreen>
</descrip>
@@ -94,7 +94,7 @@ be used in presence of a prototype.
<ref id="tgi_pieslice" name="tgi_pieslice">,
<ref id="tgi_setcolor" name="tgi_setcolor">
<tag/Example/<tscreen><verb>
tgi_setcolor(TGI_COLOR_BLACK);
tgi_setcolor(1);
tgi_circle(50, 40, 40);
</verb></tscreen>
</descrip>
@@ -154,7 +154,7 @@ be used in presence of a prototype.
<ref id="tgi_pieslice" name="tgi_pieslice">,
<ref id="tgi_setcolor" name="tgi_setcolor">
<tag/Example/<tscreen><verb>
tgi_setcolor(TGI_COLOR_RED);
tgi_setcolor(1);
tgi_ellipse (50, 40, 40, 20);
</verb></tscreen>
</descrip>
@@ -216,17 +216,19 @@ original aspect ratio.
<quote>
<descrip>
<tag/Function/Return the current drawing color.
<tag/Function/Return the current drawing color (palette index).
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
<tag/Declaration/<tt/unsigned char tgi_getcolor (void);/
<tag/Description/The actual color is an index to a palette. During tgi_init
you will get a default palette. The number of colors depend on the platform.
All platforms recognize at least TGI_COLOR_BLACK and TGI_COLOR_WHITE. But some
platforms have many more predefined colors. If you paint using TGI_COLOR_GREEN
and then you change the green of the palette to blue using tgi_setpalette then
after this painting in TGI_COLOR_GREEN will actually be blue.
you will get a default palette.
A default palette has always two entries with values equal to TGI_COLOR_BLACK
and TGI_COLOR_WHITE. However, which default palette entries have those two
values is target specific.
Note that both the number of colors, and also the available colors, depend on
the target and/or driver.
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/See also/<ref id="tgi_setcolor" name="tgi_setcolor">,
<ref id="tgi_setpalette" name="tgi_setpalette">
<tag/Example/<tscreen><verb>
color = tgi_getcolor();
</verb></tscreen>
@@ -238,7 +240,8 @@ color = tgi_getcolor();
<quote>
<descrip>
<tag/Function/Get the number of available colors.
<tag/Function/Get the number of available colors in the palette for the current
driver.
<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
@@ -287,8 +290,6 @@ if (num_colors == 0) {
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
<tag/Declaration/<tt/const unsigned char* tgi_getdefpalette (void);/
<tag/Description/The tgi driver has a default palette that is active at startup.
The named colors TGI_COLOR_BLACK, TGI_COLOR_WHITE, TGI_COLOR_RED... need this
palette to work correctly.
<tag/Availability/cc65
<tag/See also/Other tgi functions
<tag/Example/None.
@@ -418,10 +419,10 @@ be used in presence of a prototype.
<quote>
<descrip>
<tag/Function/Get the color of a pixel from the viewpage.
<tag/Function/Get the color (palette index) of a pixel from the viewpage.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
<tag/Declaration/<tt/unsigned char __fastcall__ tgi_getpixel (int x, int y);/
<tag/Description/Get the color of a pixel from the viewpage.
<tag/Description/Get the color (palette index) of a pixel from the viewpage.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
@@ -477,10 +478,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.
@@ -626,7 +627,7 @@ be used in presence of a prototype.
#define tgi_updatedisplay() tgi_ioctl(4, (void*)1)
if (!tgi_busy()) {
tgi_sprite(&amp;background);
tgi_setcolor(TGI_COLOR_BLUE);
tgi_setcolor(1);
tgi_outttextxy(20,40,"Hello World");
tgi_updatedisplay();
}
@@ -791,7 +792,7 @@ of range.
<ref id="tgi_setcolor" name="tgi_setcolor">
<tag/Example/<tscreen><verb>
/* Draw the closed upper half of an ellipse */
tgi_setcolor(TGI_COLOR_BLUE);
tgi_setcolor(1);
tgi_pieslice (50, 50, 40, 20, 0, 180);
</verb></tscreen>
</descrip>
@@ -834,20 +835,21 @@ only in the presence of a prototype.
<quote>
<descrip>
<tag/Function/Set color to be used in future draw operations.
<tag/Function/Set color (palette index) to be used in future draw operations.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
<tag/Declaration/<tt/void __fastcall__ tgi_setcolor (unsigned char color);/
<tag/Description/Set color to be used in future draw operations.
<tag/Declaration/<tt/void __fastcall__ tgi_setcolor (unsigned char color_index);/
<tag/Description/Set color (palette index) to be used in future draw operations.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/See also/<ref id="tgi_getcolor" name="tgi_getcolor">,
<ref id="tgi_setpalette" name="tgi_setpalette">
<tag/Example/<tscreen><verb>
tgi_setcolor(TGI_COLOR_BLACK);
tgi_setcolor(1);
tgi_bar(0,0,30,30);
tgi_setcolor(TGI_COLOR_WHITE);
tgi_setcolor(2);
tgi_bar(10,10,20,20);
</verb></tscreen>
</descrip>
@@ -893,13 +895,21 @@ Palette is a pointer to as many entries as there are colors.
<tag/Header/<tt/<ref id="tgi.h" name="tgi.h">/
<tag/Declaration/<tt/void __fastcall__ tgi_setpalette (const unsigned char* palette);/
<tag/Description/Set the palette (not available with all drivers/hardware).
Palette is a pointer to as many entries as there are colors.
Palette is a pointer to as many entries as there are colors. The values in the
palette are target specific, some (hopefully, more or less) portable values are
defined in the TGI_COLOR_XY defines. Note that different platforms provide
different colors, only TGI_COLOR_BLACK and TGI_COLOR_WHITE are guaranteed to
exist (needed for the default palette).
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
<item>The palette is the (only) place where to use the TGI_COLOR_XY values. This
has been an ongoing and reoccurring misunderstanding in the past: At every other
place, the "color" values are indices into the current palette.
</itemize>
<tag/Availability/cc65
<tag/See also/Other tgi functions.
<tag/See also/<ref id="tgi_setcolor" name="tgi_setcolor">,
<ref id="tgi_getpalette" name="tgi_getpalette">
<tag/Example/None.
</descrip>
</quote>