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

Merge branch 'master' into master

Browse Source
This commit is contained in:
jedeoric
2017-10-22 23:11:18 +02:00
committed by GitHub
parent 93f202850a 4da1d3232f
commit af1c7f0c8b
267 changed files with 9426 additions and 5145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/Makefile
View File

@@ -6,8 +6,8 @@ endif
.SUFFIXES:
htmldir = $(prefix)/share/doc/cc65$(DESTPACKAGE_SUFFIX)/html
infodir = $(prefix)/share/info
htmldir = $(PREFIX)/share/doc/cc65$(DESTPACKAGE_SUFFIX)/html
infodir = $(PREFIX)/share/info
ifdef CMD_EXE
@@ -46,7 +46,7 @@ clean:
$(RM) -r ../html ../info
install:
$(if $(prefix),,$(error variable `prefix' must be set))
$(if $(PREFIX),,$(error variable `PREFIX' must be set))
ifeq ($(wildcard ../html),../html)
$(INSTALL) -d $(DESTDIR)$(htmldir)
$(INSTALL) -m0644 ../html/*.* $(DESTDIR)$(htmldir)

105
doc/apple2.sgml
View File

@@ -435,7 +435,7 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3:
<tag/Interrupts/
There's no <tt/interruptor/ support. Any attempt to use it yields the message
'FAILED TO ALLOC INTERRUPT' on program startup. This implicitly means that
<tt/a2.stdmou.mou/ and <tt/a2.ssc.ser/ are not functional as they depend on
joystick, mouse and RS232 device drivers are not functional as they depend on
interrupts.
</descrip><p>
@@ -511,6 +511,109 @@ url="ca65.html" name="assembler manual">.
</descrip><p>
<sect1>Specifying file types for fopen<p>
<descrip>
<tag>Explanation of File Types</tag>
ProDOS associates a file type and an auxiliary type with each file.
These type specifications are separate from the file's name, unlike
Windows which uses the file name's suffix (a.k.a.
extension) to specify the file type. For example, <tt/.exe/,
<tt/.doc/, or <tt/.bat/.
The ProDOS low-level
Machine-Language Interface (MLI) functions for creating and opening
files require these types to be specified. And if they don't match
with the file being opened, the operation may fail.
In contrast, the ISO C function <tt/fopen()/ and the POSIX function
<tt/open()/ have no parameter to specify either a file type or an
auxiliary type. Therefore, some additional mechanism for specifying
the file types is needed.
<tag>Specifying the File Type and Auxiliary Type</tag>
There are two global variables provided that allow the file type
and auxiliary type to be specified before a call to <tt/fopen()/
or <tt/open()/. They are defined in <tt/apple2_filetype.h/:
<tscreen>
<verb>
extern unsigned char _filetype; /* Default: PRODOS_T_BIN */
extern unsigned int _auxtype; /* Default: 0 */
</verb>
</tscreen>
The header file <tt/apple2_filetype.h/ also defines many values
that can be used to set these variables. It is included in
<tt/apple2.h/, which is in turn included in <tt/apple2enh.h/.
So it isn't necessary to include it directly. Just
include one of <tt/apple2.h/ or <tt/apple2enh.h/.
<tag>Example</tag>
A text file cannot be created with just the
standard C functions because they default to the binary type
<tt/PRODOS_T_BIN/. The <tt/_filetype/ variable must be set to
<tt/PRODOS_T_TXT/ to create a text file.
For a text file,
<tt/_auxtype/ specifies the record length. A zero record
length text file is referred to as a sequential text file.
This is equivalent to text files on
other operating systems, except that the line terminator is a
carriage return instead of a line-feed (Linux/BSD/MacOS) or
carriage return, line-feed pair (Windows).
The "sequential" text file terminology is in contrast to a
"random-access" text file which would
have a fixed-length, non-zero record length, so that the
file position of any individual record can be calculated.
For this example, the
<tt/_auxtype/ does not need to be set because it defaults to
the desired value, which is zero. To be more explicit,
<tt/_auxtype/ can also be set to <tt/PRODOS_AUX_T_TXT_SEQ/
which is defined as zero.
<tscreen>
<verb>
&num;include &lt;stdio.h&gt;
&num;include &lt;string.h&gt;
&num;include &lt;errno.h&gt;
&num;include &lt;apple2.h&gt;
void main(void)
{
FILE *out;
char *name = "MY.FAVS";
/*-----------------------------*/
_filetype = PRODOS_T_TXT;
_auxtype = PRODOS_AUX_T_TXT_SEQ;
/*-----------------------------*/
if ((out = fopen(name, "w")) != NULL) {
fputs("Jorah Mormont\r", out);
fputs("Brienne of Tarth\r", out);
fputs("Daenerys Targaryen\r", out);
fputs("Sandor Clegane\r", out);
if (fclose(out) == EOF) {
fprintf(stderr, "fclose failed for %s: %s", name, strerror(errno));
}
}
else {
fprintf(stderr, "fopen failed for %s: %s", name, strerror(errno));
}
}
</verb>
</tscreen>
</descrip><p>
<sect>License<p>

105
doc/apple2enh.sgml
View File

@@ -436,7 +436,7 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3:
<tag/Interrupts/
There's no <tt/interruptor/ support. Any attempt to use it yields the message
'Failed to alloc interrupt' on program startup. This implicitly means that
<tt/a2e.stdmou.mou/ and <tt/a2e.ssc.ser/ are not functional as they depend on
joystick, mouse and RS232 device drivers are not functional as they depend on
interrupts.
</descrip><p>
@@ -517,6 +517,109 @@ url="ca65.html" name="assembler manual">.
</descrip><p>
<sect1>Specifying file types for fopen<p>
<descrip>
<tag>Explanation of File Types</tag>
ProDOS associates a file type and an auxiliary type with each file.
These type specifications are separate from the file's name, unlike
Windows which uses the file name's suffix (a.k.a.
extension) to specify the file type. For example, <tt/.exe/,
<tt/.doc/, or <tt/.bat/.
The ProDOS low-level
Machine-Language Interface (MLI) functions for creating and opening
files require these types to be specified. And if they don't match
with the file being opened, the operation may fail.
In contrast, the ISO C function <tt/fopen()/ and the POSIX function
<tt/open()/ have no parameter to specify either a file type or an
auxiliary type. Therefore, some additional mechanism for specifying
the file types is needed.
<tag>Specifying the File Type and Auxiliary Type</tag>
There are two global variables provided that allow the file type
and auxiliary type to be specified before a call to <tt/fopen()/
or <tt/open()/. They are defined in <tt/apple2_filetype.h/:
<tscreen>
<verb>
extern unsigned char _filetype; /* Default: PRODOS_T_BIN */
extern unsigned int _auxtype; /* Default: 0 */
</verb>
</tscreen>
The header file <tt/apple2_filetype.h/ also defines many values
that can be used to set these variables. It is included in
<tt/apple2.h/, which is in turn included in <tt/apple2enh.h/.
So it isn't necessary to include it directly. Just
include one of <tt/apple2.h/ or <tt/apple2enh.h/.
<tag>Example</tag>
A text file cannot be created with just the
standard C functions because they default to the binary type
<tt/PRODOS_T_BIN/. The <tt/_filetype/ variable must be set to
<tt/PRODOS_T_TXT/ to create a text file.
For a text file,
<tt/_auxtype/ specifies the record length. A zero record
length text file is referred to as a sequential text file.
This is equivalent to text files on
other operating systems, except that the line terminator is a
carriage return instead of a line-feed (Linux/BSD/MacOS) or
carriage return, line-feed pair (Windows).
The "sequential" text file terminology is in contrast to a
"random-access" text file which would
have a fixed-length, non-zero record length, so that the
file position of any individual record can be calculated.
For this example, the
<tt/_auxtype/ does not need to be set because it defaults to
the desired value, which is zero. To be more explicit,
<tt/_auxtype/ can also be set to <tt/PRODOS_AUX_T_TXT_SEQ/
which is defined as zero.
<tscreen>
<verb>
&num;include &lt;stdio.h&gt;
&num;include &lt;string.h&gt;
&num;include &lt;errno.h&gt;
&num;include &lt;apple2.h&gt;
void main(void)
{
FILE *out;
char *name = "MY.FAVS";
/*-----------------------------*/
_filetype = PRODOS_T_TXT;
_auxtype = PRODOS_AUX_T_TXT_SEQ;
/*-----------------------------*/
if ((out = fopen(name, "w")) != NULL) {
fputs("Jorah Mormont\r", out);
fputs("Brienne of Tarth\r", out);
fputs("Daenerys Targaryen\r", out);
fputs("Sandor Clegane\r", out);
if (fclose(out) == EOF) {
fprintf(stderr, "fclose failed for %s: %s", name, strerror(errno));
}
}
else {
fprintf(stderr, "fopen failed for %s: %s", name, strerror(errno));
}
}
</verb>
</tscreen>
</descrip><p>
<sect>License<p>

31
doc/ar65.sgml
View File

@@ -4,7 +4,7 @@
<title>ar65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>19.07.2000
<date>2017-05-28
<abstract>
ar65 is an archiver for object files generated by ca65. It allows to create
@@ -32,16 +32,17 @@ for the cc65 compiler. ar65 is part of this suite.
The archiver is called as follows:
<tscreen><verb>
Usage: ar65 <operation> lib file|module ...
Operation is one of:
a Add modules
d Delete modules
l List library contents
x Extract modules
V Print the archiver version
Usage: ar65 <operation ...> lib file|module ...
Operations are some of:
r Add modules
d Delete modules
t List library table
v Increase verbosity (put before other operation)
x Extract modules
V Print the archiver version
</verb></tscreen>
You may add modules to a library using the `a' command. If the library
You may add modules to a library using the `r' command (`a' is deprecated). If the library
does not exist, it is created (and a warning message is printed which you
may ignore if creation of the library was your intention). You may
specify any number of modules on the command line following the library.
@@ -53,7 +54,7 @@ has a newer timestamp than the one to add.
Here's an example:
<tscreen><verb>
ar65 a mysubs.lib sub1.o sub2.o
ar65 r mysubs.lib sub1.o sub2.o
</verb></tscreen>
This will add two modules to the library `mysubs.lib' creating the
@@ -63,10 +64,10 @@ sub2.o, they are replaced by the new ones.
Modules names in the library are stored without the path, so, using
<tscreen><verb>
ar65 a mysubs.lib ofiles/sub1.o ofiles/sub2.o
ar65 v v r mysubs.lib ofiles/sub1.o ofiles/sub2.o
</verb></tscreen>
will add two modules named `sub1.o' and `sub2.o' to the library.
will verbose add two modules named `sub1.o' and `sub2.o' to the library.
Deleting modules from a library is done with the `d' command. You may not
give a path when naming the modules.
@@ -81,13 +82,13 @@ This will delete the module named `sub1.o' from the library, printing an
error if the library does not contain that module.
The `l' command prints a list of all modules in the library. Any module
names on the command line are ignored.
The `t' command prints a table of all modules in the library (`l' is deprecated).
Any module names on the command line are ignored.
Example:
<tscreen><verb>
ar65 l mysubs.lib
ar65 tv mysubs.lib
</verb></tscreen>

53
doc/ca65.sgml
View File

@@ -1636,7 +1636,7 @@ either a string or an expression.
<tscreen><verb>
; Reserve space for the larger of two data blocks
savearea: .max (.sizeof (foo), .sizeof (bar))
savearea: .res .max (.sizeof (foo), .sizeof (bar))
</verb></tscreen>
See: <tt><ref id=".MIN" name=".MIN"></tt>
@@ -1695,8 +1695,8 @@ either a string or an expression.
Example:
<tscreen><verb>
; Reserve space for some data, but 256 bytes minimum
savearea: .min (.sizeof (foo), 256)
; Reserve space for some data, but 256 bytes maximum
savearea: .res .min (.sizeof (foo), 256)
</verb></tscreen>
See: <tt><ref id=".MAX" name=".MAX"></tt>
@@ -4305,6 +4305,13 @@ different:
some things may be done with both macro types, each type has special
usages. The types complement each other.
<item> Parentheses work differently from C macros.
The common practice of wrapping C macros in parentheses may cause
unintended problems here, such as accidentally implying an
indirect addressing mode. While the definition of a macro requires
parentheses around its argument list, when invoked they should not be
included.
</itemize>
Let's look at a few examples to make the advantages and disadvantages
@@ -4337,18 +4344,42 @@ Macros with parameters may also be useful:
DEBUG "Assembling include file #3"
</verb></tscreen>
Note that, while formal parameters have to be placed in braces, this is
not true for the actual parameters. Beware: Since the assembler cannot
detect the end of one parameter, only the first token is used. If you
don't like that, use classic macros instead:
Note that, while formal parameters have to be placed in parentheses,
the actual argument used when invoking the macro should not be.
The invoked arguments are separated by commas only, if parentheses are
used by accident they will become part of the replaced token.
If you wish to have an expression follow the macro invocation, the
last parameter can be enclosed in curly braces {} to indicate the end of that
argument.
Examples:
<tscreen><verb>
.macro DEBUG message
.out message
.endmacro
.define COMBINE(ta,tb,tc) ta+tb*10+tc*100
.word COMBINE 5,6,7 ; 5+6*10+7*100 = 765
.word COMBINE(5,6,7) ; (5+6*10+7)*100 = 7200 ; incorrect use of parentheses
.word COMBINE 5,6,7+1 ; 5+6*10+7+1*100 = 172
.word COMBINE 5,6,{7}+1 ; 5+6*10+7*100+1 = 766 ; {} encloses the argument
.word COMBINE 5,6-2,7 ; 5+6-2*10+7*100 = 691
.word COMBINE 5,(6-2),7 ; 5+(6-2)*10+7*100 = 745
.word COMBINE 5,6,7+COMBINE 0,1,2 ; 5+6*10+7+0+1*10+2*100*100 = 20082
.word COMBINE 5,6,{7}+COMBINE 0,1,2 ; 5+6*10+7*100+0+1*10+2*100 = 975
</verb></tscreen>
(That is an example where a problem can be solved with both macro types).
With C macros it is common to enclose the results in parentheses to
prevent unintended interactions with the text of the arguments, but
additional care must be taken in this assembly context where parentheses
may alter the meaning of a statement. In particular, indirect addressing modes
may be accidentally implied:
<tscreen><verb>
.define DUO(ta,tb) (ta+(tb*10))
lda DUO(5,4), Y ; LDA (indirect), Y
lda 0+DUO(5,4), Y ; LDA absolute indexed, Y
</verb></tscreen>
<sect1>Characters in macros<p>

2
doc/cbm510.sgml
View File

@@ -67,7 +67,7 @@ Special locations:
<descrip>
<tag/Stack/
The C runtime stack is located at &dollar;FF81, and grows downwards.
The C runtime stack is located at &dollar;FEC2, and grows downwards.
<tag/Heap/
The C heap is located at the end of the program, and grows towards the C

394
doc/cc65.sgml
View File

@@ -4,7 +4,7 @@
<title>cc65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:gregdk@users.sf.net" name="Greg King">
<date>2016-06-11
<date>2017-05-20
<abstract>
cc65 is a C compiler for 6502 targets. It supports several 6502 based home
@@ -58,7 +58,7 @@ Short options:
-O Optimize code
-Oi Optimize code, inline more code
-Or Enable register variables
-Os Inline some known functions
-Os Inline some standard functions
-T Include source as comment
-V Print the compiler version number
-W warning[,...] Suppress warnings
@@ -88,9 +88,11 @@ Long options:
--debug-opt name Debug optimization steps
--dep-target target Use this dependency target
--disable-opt name Disable an optimization step
--eagerly-inline-funcs Eagerly inline some known functions
--enable-opt name Enable an optimization step
--help Help (this text)
--include-dir dir Set an include directory search path
--inline-stdfuncs Inline some standard functions
--list-opt-steps List all optimizer steps and exit
--list-warnings List available warning types for -W
--local-strings Emit string literals immediately
@@ -219,11 +221,53 @@ Here is a description of all the command line options:
symbols in a special section in the object file.
<label id="option-eagerly-inline-funcs">
<tag><tt>--eagerly-inline-funcs</tt></tag>
Have the compiler eagerly inline these functions from the C library:
<itemize>
<item><tt/memcpy()/
<item><tt/memset()/
<item><tt/strcmp()/
<item><tt/strcpy()/
<item><tt/strlen()/
<item>most of the functions declared in <tt/&lt;ctype.h&gt;/
</itemize>
Note: This has two consequences:
<itemize>
<item>You may not use names of standard C functions for your own functions.
If you do that, your program is not standard-compliant anyway; but,
using <tt/--eagerly-inline-funcs/ actually will break things.
<p>
<item>The inlined string and memory functions will not handle strings or
memory areas larger than 255 bytes. Similarly, the inlined <tt/is..()/
functions will not work with values outside the char. range (such as
<tt/EOF/).
<p>
</itemize>
<tt/--eagerly-inline-funcs/ implies the <tt><ref id="option-inline-stdfuncs"
name="--inline-stdfuncs"></tt> command line option.
See also <tt><ref id="pragma-allow-eager-inline" name="#pragma&nbsp;allow-eager-inline"></tt>.
<tag><tt>-h, --help</tt></tag>
Print the short option summary shown above.
<label id="option-inline-stdfuncs">
<tag><tt>--inline-stdfuncs</tt></tag>
Allow the compiler to inline some standard functions from the C library like
strlen. This will not only remove the overhead for a function call, but will
make the code visible for the optimizer. See also the <tt><ref id="option-O"
name="-Os"></tt> command line option and <tt><ref id="pragma-inline-stdfuncs"
name="#pragma&nbsp;inline-stdfuncs"></tt>.
<label id="option-list-warnings">
<tag><tt>--list-warnings</tt></tag>
@@ -392,22 +436,22 @@ Here is a description of all the command line options:
using
<tscreen><verb>
void f (void)
{
unsigned a = 1;
...
}
void f (void)
{
unsigned a = 1;
...
}
</verb></tscreen>
the variable <tt/a/ will always have the value <tt/1/ when entering the
function and using <tt/-Cl/, while in
<tscreen><verb>
void f (void)
{
static unsigned a = 1;
....
}
void f (void)
{
static unsigned a = 1;
....
}
</verb></tscreen>
the variable <tt/a/ will have the value <tt/1/ only the first time that the
@@ -444,23 +488,14 @@ Here is a description of all the command line options:
name="--register-vars">/ command line option, and the <ref
id="register-vars" name="discussion of register variables"> below.
Using <tt/-Os/ will force the compiler to inline some known functions from
the C library like strlen. Note: This has two consequences:
<p>
<itemize>
<item>You may not use names of standard C functions in your own code. If you
do that, your program is not standard compliant anyway, but using
<tt/-Os/ will actually break things.
<p>
<item>The inlined string and memory functions will not handle strings or
memory areas larger than 255 bytes. Similarly, the inlined <tt/is..()/
functions will not work with values outside the char. range (such as
<tt/EOF/).
<p>
</itemize>
<p>
Using <tt/-Os/ will allow the compiler to inline some standard functions
from the C library like strlen. This will not only remove the overhead
for a function call, but will make the code visible for the optimizer.
See also the <tt/<ref id="option-inline-stdfuncs" name="--inline-stdfuncs">/
command line option.
It is possible to concatenate the modifiers for <tt/-O/. For example, to
enable register variables and inlining of known functions, you may use
enable register variables and inlining of standard functions, you may use
<tt/-Ors/.
@@ -518,6 +553,7 @@ Here is a description of all the command line options:
</descrip><p>
<sect>Input and output<p>
The compiler will accept one C file per invocation and create a file with
@@ -556,21 +592,21 @@ and the one defined by the ISO standard:
<itemize>
<item> The datatypes "float" and "double" are not available.
<p>
<item> C Functions may not return structs (or unions), and structs may not
<item> The datatypes "float" and "double" are not available.
<p>
<item> C Functions may not return structs (or unions), and structs may not
be passed as parameters by value. However, struct assignment *is*
possible.
<p>
<item> Most of the C library is available with only the fastcall calling
convention (<ref id="extension-fastcall" name="see below">). It means
that you must not mix pointers to those functions with pointers to
user-written, cdecl functions (the calling conventions are incompatible).
<p>
<item> The <tt/volatile/ keyword has almost no effect. That is not as bad
possible.
<p>
<item> Most of the C library is available with only the fastcall calling
convention (<ref id="extension-fastcall" name="see below">). It means
that you must not mix pointers to those functions with pointers to
user-written, cdecl functions (the calling conventions are incompatible).
<p>
<item> The <tt/volatile/ keyword has almost no effect. That is not as bad
as it sounds, since the 6502 has so few registers that it isn't
possible to keep values in registers anyway.
<p>
<p>
</itemize>
There may be some more minor differences I'm currently not aware of. The
@@ -585,49 +621,48 @@ This cc65 version has some extensions to the ISO C standard.
<itemize>
<item> The compiler allows to insert assembler statements into the output
file. The syntax is
<item> The compiler allows to insert assembler statements into the output
file. The syntax is
<tscreen><verb>
asm [optional volatile] (&lt;string literal&gt;[, optional parameters]) ;
</verb></tscreen>
or
<tscreen><verb>
<tscreen><verb>
asm [optional volatile] (&lt;string literal&gt;[, optional parameters]) ;
</verb></tscreen>
or
<tscreen><verb>
__asm__ [optional volatile] (&lt;string literal&gt;[, optional parameters]) ;
</verb></tscreen>
</verb></tscreen>
The first form is in the user namespace; and, is disabled if the <tt/-A/
switch is given.
The first form is in the user namespace; and, is disabled if the <tt/-A/
switch is given.
There is a whole section covering inline assembler statements,
<ref id="inline-asm" name="see there">.
<p>
There is a whole section covering inline assembler statements,
<ref id="inline-asm" name="see there">.
<p>
<label id="extension-fastcall">
<item> The normal calling convention -- for non-variadic functions -- is
named "fastcall". The syntax for a function declaration that
<em/explicitly/ uses fastcall is
<item> The normal calling convention -- for non-variadic functions -- is
named "fastcall". The syntax for a function declaration that
<em/explicitly/ uses fastcall is
<tscreen><verb>
&lt;return type&gt; fastcall &lt;function name&gt; (&lt;parameter list&gt;)
</verb></tscreen>
or
<tscreen><verb>
&lt;return type&gt; __fastcall__ &lt;function name&gt; (&lt;parameter list&gt;)
</verb></tscreen>
An example is
<tscreen><verb>
void __fastcall__ f (unsigned char c)
</verb></tscreen>
The first form of the fastcall keyword is in the user namespace and can
therefore be disabled with the <tt><ref id="option--standard"
<tscreen><verb>
&lt;return type&gt; fastcall &lt;function name&gt; (&lt;parameter list&gt;)
</verb></tscreen>
or
<tscreen><verb>
&lt;return type&gt; __fastcall__ &lt;function name&gt; (&lt;parameter list&gt;)
</verb></tscreen>
An example is
<tscreen><verb>
void __fastcall__ f (unsigned char c)
</verb></tscreen>
The first form of the fastcall keyword is in the user namespace and can
therefore be disabled with the <tt><ref id="option--standard"
name="--standard"></tt> command line option.
For functions that are <tt/fastcall/, the rightmost parameter is not
pushed on the stack but left in the primary register when the function
is called. That significantly reduces the cost of calling those functions.
<newline><newline>
<p>
For functions that are <tt/fastcall/, the rightmost parameter is not
pushed on the stack but left in the primary register when the function
is called. That significantly reduces the cost of calling those functions.
<p>
<item> There is another calling convention named "cdecl". Variadic functions
(their prototypes have an ellipsis &lsqb;<tt/.../&rsqb;) always use that
@@ -652,65 +687,72 @@ This cc65 version has some extensions to the ISO C standard.
For functions that are <tt/cdecl/, the rightmost parameter is pushed
onto the stack before the function is called. That increases the cost
of calling those functions, especially when they are called from many
places.<newline><newline>
places.
<p>
<item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/.
Both refer to the primary register that is used by the compiler to
evaluate expressions or return function results. <tt/__AX__/ is of
type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/
respectively. The pseudo variables may be used as lvalue and rvalue as
every other variable. They are most useful together with short
sequences of assembler code. For example, the macro
<item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/.
Both refer to the primary register that is used by the compiler to
evaluate expressions or return function results. <tt/__AX__/ is of
type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/
respectively. The pseudo variables may be used as lvalue and rvalue as
every other variable. They are most useful together with short
sequences of assembler code. For example, the macro
<tscreen><verb>
#define hi(x) \
<tscreen><verb>
#define hi(x) \
(__AX__ = (x), \
asm ("txa"), \
asm ("ldx #$00"), \
__AX__)
</verb></tscreen>
</verb></tscreen>
will give the high byte of any unsigned value.
<p>
will give the high byte of any unsigned value.
<p>
<item> Inside a function, the identifier <tt/__func__/ gives the name of the
current function as a string. Outside of functions, <tt/__func__/ is
undefined.
Example:
<item> Inside a function, the identifier <tt/__func__/ gives the name of the
current function as a string. Outside of functions, <tt/__func__/ is
undefined.
Example:
<tscreen><verb>
#define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s);
</verb></tscreen>
<tscreen><verb>
#define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s);
</verb></tscreen>
The macro will print the name of the current function plus a given
string.
<p>
The macro will print the name of the current function plus a given
string.
<p>
<item> cc65 allows the initialization of <tt/void/ variables. This may be
used to create variable structures that are more compatible with
interfaces written for assembler languages. Here is an example:
<item> cc65 allows the initialization of <tt/void/ variables. This may be
used to create arbitrary structures that are more compatible with
interfaces written for assembler languages. Here is an example:
<tscreen><verb>
void GCmd = { (char)3, (unsigned)0x2000, (unsigned)0x3000 };
</verb></tscreen>
<tscreen><verb>
void GCmd = { (char)3, (unsigned)0x2000, (unsigned)0x3000 };
</verb></tscreen>
This will be translated as follows:
That will be translated as follows:
<tscreen><verb>
_GCmd:
.byte 3
.word $2000
.word $3000
</verb></tscreen>
<tscreen><verb>
_GCmd:
.byte 3
.word $2000
.word $3000
</verb></tscreen>
Since the variable is of type <tt/void/ you may not use it as is.
However, taking the address of the variable results in a <tt/void*/
which may be passed to any function expecting a pointer.
Since the variable is of type <tt/void/, you may not use it as-is.
However, taking the address of the variable results in a <tt/void*/
which may be passed to any function expecting a pointer. Also, the
<tt/sizeof/ operator will give the length of the initializer:
See the <url url="geos.html" name="GEOS library document"> for examples
on how to use this feature.
<p>
<tscreen><verb>
GLen = sizeof GCmd;
</verb></tscreen>
will assign the value 5 to <tt/GLen/.
See the <url url="geos.html" name="GEOS library document"> for examples
on how to use that feature.
<p>
<item> cc65 implements flexible array struct members as defined in the C99 ISO
standard. As an extension, these fields may be initialized. There are
@@ -818,6 +860,11 @@ The compiler defines several macros at startup:
This macro expands to the date of translation of the preprocessing
translation unit in the form "Mmm dd yyyy".
<tag><tt>__EAGERLY_INLINE_FUNCS__</tt></tag>
Is defined if the compiler was called with the <tt><ref id="option-eagerly-inline-funcs"
name="--eagerly-inline-funcs"></tt> command line option.
<tag><tt>__FILE__</tt></tag>
This macro expands to a string containing the name of the C source file.
@@ -905,6 +952,7 @@ The compiler defines several macros at startup:
</descrip>
<sect>&num;pragmas<label id="pragmas"><p>
The compiler understands some pragmas that may be used to change code
@@ -913,6 +961,19 @@ If the first parameter is <tt/push/, the old value is saved onto a stack
before changing it. The value may later be restored by using the <tt/pop/
parameter with the <tt/#pragma/.
<sect1><tt>#pragma allow-eager-inline ([push,] on|off)</tt><label id="pragma-allow-eager-inline"><p>
Allow eager inlining of known functions. If the argument is "off", eager
inlining is disabled, otherwise it is enabled. Please note that (in contrast
to the <tt><ref id="option-eagerly-inline-funcs" name="--eagerly-inline-funcs"></tt>
command line option) this pragma does not imply the <tt><ref id="option-inline-stdfuncs"
name="--inline-stdfuncs"></tt> command line option. Rather it marks code to be safe for
eager inlining of known functions if inlining of standard functions is enabled.
The <tt/#pragma/ understands the push and pop parameters as explained above.
<sect1><tt>#pragma bss-name (&lsqb;push,&rsqb; &lt;name&gt;)</tt><label id="pragma-bss-name"><p>
This pragma changes the name used for the BSS segment (the BSS segment
@@ -931,7 +992,7 @@ parameter with the <tt/#pragma/.
Example:
<tscreen><verb>
#pragma bss-name ("MyBSS")
#pragma bss-name ("MyBSS")
</verb></tscreen>
@@ -986,6 +1047,7 @@ parameter with the <tt/#pragma/.
The <tt/#pragma/ understands the push and pop parameters as explained above.
<sect1><tt>#pragma code-name ([push,] &lt;name&gt;)</tt><label id="pragma-code-name"><p>
This pragma changes the name used for the CODE segment (the CODE segment
@@ -1000,7 +1062,7 @@ parameter with the <tt/#pragma/.
Example:
<tscreen><verb>
#pragma code-name ("MyCODE")
#pragma code-name ("MyCODE")
</verb></tscreen>
@@ -1028,10 +1090,21 @@ parameter with the <tt/#pragma/.
Example:
<tscreen><verb>
#pragma data-name ("MyDATA")
#pragma data-name ("MyDATA")
</verb></tscreen>
<sect1><tt>#pragma inline-stdfuncs ([push,] on|off)</tt><label id="pragma-inline-stdfuncs"><p>
Allow the compiler to inline some standard functions from the C library like
strlen. If the argument is "off", inlining is disabled, otherwise it is enabled.
See also the <tt/<ref id="option-inline-stdfuncs" name="--inline-stdfuncs">/
command line option.
The <tt/#pragma/ understands the push and pop parameters as explained above.
<sect1><tt>#pragma local-strings ([push,] on|off)</tt><label id="pragma-local-strings"><p>
When "on", emit string literals to the data segment when they're encountered
@@ -1046,6 +1119,23 @@ parameter with the <tt/#pragma/.
remembered and output as a whole when translation is finished.
<sect1><tt>#pragma message (&lt;message&gt;)</tt><label id="pragma-message"><p>
This pragma is used to display informational messages at compile-time.
The message intented to be displayed must be a string literal.
Example:
<tscreen><verb>
#pragma message ("in a bottle")
</verb></tscreen>
Results in the compiler outputting the following to stderr:
<tscreen><verb>
example.c(42): Note: in a bottle
</verb></tscreen>
<sect1><tt>#pragma optimize ([push,] on|off)</tt><label id="pragma-optimize"><p>
Switch optimization on or off. If the argument is "off", optimization is
@@ -1076,7 +1166,7 @@ parameter with the <tt/#pragma/.
Example:
<tscreen><verb>
#pragma rodata-name ("MyRODATA")
#pragma rodata-name ("MyRODATA")
</verb></tscreen>
@@ -1098,9 +1188,9 @@ parameter with the <tt/#pragma/.
Example:
<tscreen><verb>
#pragma regvaraddr(on) /* Allow taking the address
* of register variables
*/
#pragma regvaraddr(on) /* Allow taking the address
* of register variables
*/
</verb></tscreen>
@@ -1147,7 +1237,7 @@ parameter with the <tt/#pragma/.
Example:
<tscreen><verb>
/* Don't warn about the unused parameter in function func */
#pragma warn (unused-param, push, off)
#pragma warn (unused-param, push, off)
static int func (int unused)
{
return 0;
@@ -1156,6 +1246,39 @@ parameter with the <tt/#pragma/.
</verb></tscreen>
<sect1><tt>#pragma wrapped-call (push, &lt;name&gt;, &lt;identifier&gt;)</tt><label id="pragma-wrapped-call"><p>
This pragma sets a wrapper for functions, often used for trampolines.
The name is a function returning <tt/void/, and taking no parameters.
It must preserve the CPU's <tt/A/ and <tt/X/ registers if it wraps any
<tt/__fastcall__/ functions that have parameters. It must preserve
the <tt/Y/ register if it wraps any variadic functions (they have "<tt/.../"
in their prototypes).
The identifier is an 8-bit number that's set into <tt/tmp4/.
The address of a wrapped function is passed in <tt/ptr4/. The wrapper can
call that function by using "<tt/jsr callptr4/".
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.
The <tt/#pragma/ requires the push or pop argument as explained above.
Example:
<tscreen><verb>
/* Note that this code can be in a header. */
void mytrampoline(void); /* Doesn't corrupt __AX__ */
#pragma wrapped-call (push, mytrampoline, 5)
void somefunc1(void);
void somefunc2(int, char *);
#pragma wrapped-call (pop)
</verb></tscreen>
<sect1><tt>#pragma writable-strings ([push,] on|off)</tt><label id="pragma-writable-strings"><p>
Changes the storage location of string literals. For historical reasons,
@@ -1180,13 +1303,12 @@ parameter with the <tt/#pragma/.
Example:
<tscreen><verb>
extern int foo;
#pragma zpsym ("foo"); /* foo is in the zeropage */
extern int foo;
#pragma zpsym ("foo"); /* foo is in the zeropage */
</verb></tscreen>
<sect>Register variables<label id="register-vars"><p>
The runtime for all supported platforms has 6 bytes of zero page space
@@ -1269,7 +1391,7 @@ that function).
As a shortcut, you can put the <tt/volatile/ qualifier in your <tt/asm/
statements. It will disable optimization for the functions in which those
<tt/asm volatile/ statements sit. The effect is the same as though you put
</#pragma optimize(push, off)/ above those functions, and </#pragma
<tt/#pragma optimize(push, off)/ above those functions, and <tt/#pragma
optimize(pop)/ below those functions.
The string literal may contain format specifiers from the following list. For
@@ -1443,14 +1565,14 @@ 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.
<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>

96
doc/cl65.sgml
View File

@@ -2,8 +2,9 @@
<article>
<title>cl65 Users Guide
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>01.08.2000, 27.11.2000, 02.10.2001
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<date>2017-10-16
<abstract>
cl65 is the compile &amp; link utility for cc65, the 6502 C compiler. It was
@@ -50,13 +51,14 @@ Short options:
-C name Use linker config file
-Cl Make local variables static
-D sym[=defn] Define a preprocessor symbol
-E Stop after the preprocessing stage
-I dir Set a compiler include directory path
-L path Specify a library search path
-Ln name Create a VICE label file
-O Optimize code
-Oi Optimize code, inline functions
-Oi Optimize code, inline more code
-Or Optimize code, honour the register keyword
-Os Optimize code, inline known C funtions
-Os Optimize code, inline standard funtions
-S Compile but don't assemble and link
-T Include source as comment
-V Print the version number
@@ -67,6 +69,7 @@ Short options:
Long options:
--add-source Include source as comment
--all-cdecl Make functions default to __cdecl__
--asm-args options Pass options to the assembler
--asm-define sym[=v] Define an assembler symbol
--asm-include-dir dir Set an assembler include directory
@@ -120,56 +123,66 @@ Long options:
---------------------------------------------------------------------------
</verb></tscreen>
Most of the options have the same meaning than the corresponding compiler,
assembler or linker option. See the documentation for these tools for an
Most of the options have the same meanings as the corresponding compiler,
assembler, and linker options. See the documentation for those tools for an
explanation. If an option is available for more than one of the tools, it
is set for all tools, where it is available. One example for this is <tt/-v/:
The compiler, the assembler and the linker are all called with the <tt/-v/
is set for all tools where it is available. One example for that is <tt/-v/:
The compiler, the assembler, and the linker are all called with the <tt/-v/
switch.
There are a few remaining options that control the behaviour of cl65:
<descrip>
<tag><tt>-E</tt></tag>
This option is passed to the cc65 compiler; and, it forces cl65 to stop
before the assembly step. That means that C-level preprocessor directives
are obeyed; and, macroes are expanded. But, the C source isn't compiled.
If the <tt/-o/ option isn't used, then the C code results are written into
files with a ".i" suffix on their base names. Assembler files, object
files, and libraries given on the command line are ignored.
<tag><tt>-S</tt></tag>
This option forces cl65 to stop after the assembly step. This means that
C files are translated into assembler files, but nothing more is done.
Assembler files, object files and libraries given on the command line
This option forces cl65 to stop before the assembly step. That means that
C files are translated into assembler files; but, nothing more is done.
Assembler files, object files, and libraries given on the command line
are ignored.
<tag><tt>-c</tt></tag>
This options forces cl65 to stop after the assembly step. This means
This option forces cl65 to stop after the assembly step. That means
that C and assembler files given on the command line are translated into
object files, but there is no link step, and object files and libraries
object files; but, there is no link step. Object files and libraries
given on the command line are ignored.
<tag><tt>-o name</tt></tag>
The -o option is used for the target name in the final step. This causes
problems, if the linker will not be called, and there are several input
files on the command line. In this case, the name given with -o will be
The -o option is used for the target name in the final step. That causes
problems if the linker will not be called, and there are several input
files on the command line. In that case, the name given with -o will be
used for all of them, which makes the option pretty useless. You
shouldn't use -o when more than one output file is created.
shouldn't use <tt/-o/ when more than one output file is created.
<tag><tt>--print-target-path</tt></tag>
This option prints the absolute path of the target file directory and exits
This option prints the absolute path of the target file directory, and exits
then. It is supposed to be used with shell backquotes or the GNU make shell
function. This way you can write build scripts or Makefiles accessing target
function. That way, you can write build scripts or Makefiles accessing target
files without any assumption about the cc65 installation path.
<tag><tt>-t sys, --target sys</tt></tag>
The default for this option is different from the compiler and linker in the
case that the option is missing: While the other tools (compiler, assembler
The default for this option is different from the compiler and linker, in the
case that the option is missing: While the other tools (compiler, assembler,
and linker) will use the "none" system settings by default, cl65 will use
the C64 as a target system by default. This was chosen since most people
"c64" as a target system by default. That was chosen because most people
seem to use cc65 to develop for the C64.
@@ -177,10 +190,10 @@ There are a few remaining options that control the behaviour of cl65:
Pass options directly to the assembler. This may be used to pass options
that aren't directly supported by cl65. Several options may be separated by
commas, the commas are replaced by spaces when passing them to the
assembler. Beware: Passing arguments directly to the assembler may interfere
with some of the defaults, because cl65 doesn't parse the options passed. So
if cl65 supports an option by itself, do not pass this option to the
commas; the commas are replaced by spaces when passing them to the
assembler. Beware: Passing arguments directly to the assembler might interfere
with some of the defaults because cl65 doesn't parse the options passed. So,
if cl65 supports an option by itself, do not pass that option to the
assembler by means of the <tt/-Wa/ switch.
@@ -188,10 +201,10 @@ There are a few remaining options that control the behaviour of cl65:
Pass options directly to the compiler. This may be used to pass options
that aren't directly supported by cl65. Several options may be separated by
commas, the commas are replaced by spaces when passing them to the
compiler. Beware: Passing arguments directly to the compiler may interfere
with some of the defaults, because cl65 doesn't parse the options passed. So
if cl65 supports an option by itself, do not pass this option to the
commas; the commas are replaced by spaces when passing them to the
compiler. Beware: Passing arguments directly to the compiler might interfere
with some of the defaults because cl65 doesn't parse the options passed. So,
if cl65 supports an option by itself, do not pass that option to the
compiler by means of the <tt/-Wc/ switch.
@@ -199,10 +212,10 @@ There are a few remaining options that control the behaviour of cl65:
Pass options directly to the linker. This may be used to pass options that
aren't directly supported by cl65. Several options may be separated by
commas, the commas are replaced by spaces when passing them to the linker.
Beware: Passing arguments directly to the linker may interfere with some of
the defaults, because cl65 doesn't parse the options passed. So if cl65
supports an option by itself, do not pass this option to the linker by means
commas; the commas are replaced by spaces when passing them to the linker.
Beware: Passing arguments directly to the linker might interfere with some of
the defaults because cl65 doesn't parse the options passed. So, if cl65
supports an option by itself, do not pass that option to the linker by means
of the <tt/-Wl/ switch.
</descrip>
@@ -211,7 +224,7 @@ There are a few remaining options that control the behaviour of cl65:
<sect>More usage<p>
Since cl65 was created to simplify the use of the cc65 development
Because cl65 was created to simplify the use of the cc65 development
package, it tries to be smart about several things.
<itemize>
@@ -219,15 +232,14 @@ package, it tries to be smart about several things.
<item> If you don't give a target system on the command line, cl65
defaults to the C64.
<item> When linking, cl65 will supply the names of the startup file and
library for the target system to the linker, so you don't have to do
that.
<item> When linking, cl65 will supply the name of the library file for
the target system to the linker; so, you don't have to do that.
<item> If the final step is the linker, and the name of the output file was
not explicitly given, cl65 will use the name of the first input file
without the extension, provided that the name of this file has an
extension. So you don't need to name the executable name in most
cases, just give the name of your "main" file as first input file.
without the extension, provided that the name of that file has an
extension. So, you don't need to give the executable name in most
cases; just give the name of your "main" file as the first input file.
</itemize>
The command line is parsed from left to right, and the actual processing tool
@@ -248,7 +260,7 @@ The type of an input file is derived from its extension:
<itemize>
<item>C files: <tt/.c/
<item>Assembler files: <tt/.s/, <tt/.asm/, <tt/.a65/
<item>Object files: <tt/.o/ <tt/.obj/
<item>Object files: <tt/.o/, <tt/.obj/
<item>Libraries: <tt/.a/, <tt/.lib/
<item>GEOS resource files: <tt/.grc/
<item>o65 files: <tt/.o65/, <tt/.emd/, <tt/.joy/, <tt/.tgi/

56
doc/funcref.sgml
View File

@@ -2,8 +2,9 @@
<article>
<title>cc65 function reference
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<date>2016-08-07
<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
<url url="mailto:greg.king5@verizon.net" name="Greg King">
<date>2017-09-02
<abstract>
cc65 is a C compiler for 6502 based systems. This function reference describes
@@ -183,6 +184,7 @@ function.
<!-- <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="kbrepeat" name="kbrepeat">
</itemize>
(incomplete)
@@ -398,6 +400,13 @@ function.
(incomplete)
<sect1><tt/lz4.h/<label id="lz4.h"><p>
<itemize>
<item><ref id="decompress_lz4" name="decompress_lz4">
</itemize>
<sect1><tt/modload.h/<label id="modload.h"><p>
<itemize>
@@ -430,7 +439,7 @@ function.
<!-- <itemize> -->
<!-- <item><ref id="get_tv" name="get_tv"> -->
<!-- <item><ref id="waitvblank" name="waitvblank"> -->
<!-- <item><ref id="waitvsync" name="waitvsync"> -->
<!-- </itemize> -->
(incomplete)
@@ -2632,6 +2641,23 @@ used in presence of a prototype.
</quote>
<sect1>decompress_lz4<label id="decompress_lz4"><p>
<quote>
<descrip>
<tag/Function/Uncompress a LZ4-compressed buffer.
<tag/Header/<tt/<ref id="lz4.h" name="lz4.h">/
<tag/Declaration/<tt/void decompress_lz4 (const unsigned char* src, unsigned char* const dst, const unsigned short uncompressed_size);/
<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.
</itemize>
<tag/Availability/cc65
<tag/Example/None.
</descrip>
</quote>
<sect1>div<label id="div"><p>
<quote>
@@ -3710,7 +3736,7 @@ fastcall function, so it may only be used in presence of a prototype.
<quote>
<descrip>
<tag/Function/Check if a given character is a a white-space character.
<tag/Function/Check if a given character is a white-space character.
<tag/Header/<tt/<ref id="ctype.h" name="ctype.h">/
<tag/Declaration/<tt/int __fastcall__ isspace (int c);/
<tag/Description/The function returns a non zero value if the given argument
@@ -4017,6 +4043,28 @@ do), the function is rather useless.
</quote>
<sect1>kbrepeat<label id="kbrepeat"><p>
<quote>
<descrip>
<tag/Function/Set the keyboard repeat mode.
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char __fastcall__ kbrepeat (unsigned char mode);/
<tag/Description/This function changes which keys have automatic repeat when
being held down for a certain time. Possible values are <tt/KBREPEAT_CURSOR/
(repeat only cursor-related keys), <tt/KBREPEAT_NONE/ (no repeat for any
keys), and <tt/KBREPEAT_ALL/ (repeat all keys). The old mode is returned, so
it can be restored later.
<tag/Notes/<itemize>
<item>The function is available only as a fastcall function; so, it may be used
only in the presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/Example/None.
</descrip>
</quote>
<sect1>labs<label id="labs"><p>
<quote>

5
doc/ld65.sgml
View File

@@ -247,10 +247,11 @@ Here is a description of all of the command-line options:
<tag><tt>-Ln</tt></tag>
This option allows you to create a file that contains all global labels and
may be loaded into the VICE emulator using the <tt/ll/ (load label) command. You
may be loaded into the VICE emulator using the <tt/ll/ (load label) command
or into the Oricutron emulator using the <tt/sl/ (symbols load) command. You
may use this to debug your code with VICE. Note: Older versions had some
bugs in the label code. If you have problems, please get the latest <url
url="http://vice-emu.sourceforge.net/" name="VICE"> version.
url="http://vice-emu.sourceforge.net" name="VICE"> version.
<label id="option-S">

4
doc/nes.sgml
View File

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

2
doc/pce.sgml
View File

@@ -77,7 +77,7 @@ Programs containing PCE specific code may use the <tt/pce.h/ header file.
<sect1>PCE specific functions<p>
<itemize>
<item>waitvblank</item>
<item>waitvsync</item>
<item>get_tv (since all PCE systems are NTSC, this always returns TV_NTSC)</item>
</itemize>

2
doc/supervision.sgml
View File

@@ -66,7 +66,7 @@ Programs containing Supervision specific code may use the <tt/supervision.h/ hea
<sect1>Supervision specific functions<p>
<itemize>
<item>waitvblank
<item>waitvsync</item>
</itemize>

35
doc/telestrat.sgml
View File

@@ -4,13 +4,15 @@
<title>Oric Telestrat-specific information for cc65
<author>
<url url="mailto:jede@oric.org" name="Jede">,<newline>
<url url="mailto:jede@oric.org" name="Jede">
<date>2017-01-22
<abstract>
An overview over the Telestrat (Telemon 2.4 & Telemon 3.x : http://orix.oric.org) runtime system as it is implemented for the cc65 C
compiler.)
</abstract>
<!-- Table of contents -->
@@ -32,25 +34,28 @@ information.
<sect>Binary format<p>
The standard binary output format generated the linker for the Telestrat target
is a machine language program with a 20 bytes header described here : http://orix.oric.org/doku.php?id=orix:header
The standard binary output format generated the linker for the Telestrat
target is a machine language program with a 20 bytes header described <url
name="here" url="http://orix.oric.org/doku.php?id=orix:header">
This header is used for Telemon 3.0.
This header is used for Telemon 3.0.
Anyway, for Telemon 2.4, there is no file management, there is no TAPE routine in Telemon, there is no way to load a binary easily.
Anyway, for Telemon 2.4, there is no file management, there is no TAPE routine in Telemon, there is no way to load a binary easily.
Stratsed (the Telestrat operating system) handles files management. Stratsed is loaded to memory from floppy disk.
Stratsed (the Telestrat operating system) handles files management. Stratsed is loaded to memory from floppy disk.
There is no tool to insert a binary in a Stratsed floppy disk.
There is no tool to insert a binary in a Stratsed floppy disk.
The only way to load a binary (for Telemon 2.4) is to :
The only way to load a binary (for Telemon 2.4) is to:
<itemize>
<item>remove the 20 bytes header
<item>download osdk : http://osdk.defence-force.org/index?page=download
<item>download <url name="osdk" url="http://osdk.defence-force.org/index?page=download">
<item>use Floppybuilder in OSDK to insert the binary with the tool (please read FloppyBuilder manual to insert your binary, and to start microdisc boot sector when Telestrat starts)
</itemize>
Please note also, that the binary converted into TAP file, will not produce a right stratsed file when tap2dsk and old2mfm are used. You will be in the case that Telestrat/Stratsed crashed when you do "DIR" command.
Please note also, that the binary converted into TAP file, will not produce
a right stratsed file when tap2dsk and old2mfm are used. You will be in the
case that Telestrat/Stratsed crashed when you do "DIR" command.
If you know the Stratsed disk format, please contact the author of this doc.
@@ -79,7 +84,7 @@ Special locations:
<sect>Platform-specific header files<p>
Programs containing Telestrat -specific code may use the <tt/telestrat.h/ header file.
Programs containing Telestrat-specific code may use the <tt/telestrat.h/ header file.
<sect1>Telestrat-specific functions<p>
@@ -162,8 +167,12 @@ Telestrat has a RS232 port, but it's not usable in cc65.
<sect1>Disk I/O<p>
Telemon 3.0 handles fopen, fread, fclose primitives. It means that this function will crash the Telestrat because Telemon 2.4 does not have these primitives.
By the way, Telemon 3.0 uses an extension "ch376 card" which handles sdcard and FAT 32 usb key. In the next version of Telemon, FT DOS, Sedoric, Stratsed will be handled in these 3 primitives (fopen, fread, fclose).
Telemon 3.0 handles fopen, fread, fclose primitives. It means that this
function will crash the Telestrat because Telemon 2.4 does not have these
primitives. By the way, Telemon 3.0 uses an extension "ch376 card" which
handles sdcard and FAT 32 usb key. In the next version of Telemon, FT DOS,
Sedoric, Stratsed will be handled in these 3 primitives (fopen, fread,
fclose).
<itemize>
<item>fclose

18
doc/vic20.sgml
View File

@@ -2,11 +2,11 @@
<article>
<title>Commodore VIC20 (aka VC20) specific information for cc65
<title>Commodore VIC20 (aka VC20 aka VIC1001) 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">
<date>2014-04-12
<date>2017-05-18
<abstract>
An overview over the VIC20 runtime system as it is implemented for the cc65 C
@@ -182,13 +182,14 @@ No VIC1011 drivers are currently available for the VIC20.
<sect>Limitations<p>
<sect>Other hints<p>
<sect1>Escape code<p>
For an Esc, press CTRL and the <tt/[/ key.
The CTRL key cannot be used to type most control characters,
entering an Esc is not possible.
<sect>Other hints<p>
<sect1>Passing arguments to the program<p>
@@ -219,8 +220,7 @@ The program return code (low byte) is passed back to BASIC by use of the
<sect1>Using extended memory<p>
The extended memory at $A000 may be added to the heap by using the following
code:
BLK5 memory may be added to the heap by using the following code:
<tscreen><verb>
/* Check for the existence of RAM */