cc65.sgml \
cl65.sgml \
dio.sgml \
- ld65.sgml
+ geos.sgml \
+ index.sgml \
+ ld65.sgml \
+ library.sgml
TXT = $(SGML:.sgml=.txt)
HTML = $(SGML:.sgml=.html)
.PHONY: dvi
dvi: $(DVI)
+# The index.html target is special, since it does not get splitted
+index.html: index.sgml
+ sgml2html --split=0 $<
+
clean:
rm -f *~
--- /dev/null
+<!doctype linuxdoc system>
+
+<article>
+<title>cc65 documentation overview
+<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
+<date>03.12.2000
+
+<abstract>
+Main documentation page, contains links to other available stuff.
+</abstract>
+
+<sect>Documentation overview<p>
+
+<descrip>
+
+ <tag><htmlurl url="BUGS" name="BUGS"></tag>
+ Known compiler bugs.
+
+ <tag><htmlurl url="CREDITS" name="CREDITS"></tag>
+ Who helped with the compiler and tools?
+
+ <tag><htmlurl url="ar65.html" name="ar65.html"></tag>
+ Describes the ar65 archiver.
+
+ <tag><htmlurl url="ca65.html" name="ca65.html"></tag>
+ Describes the ca65 macro assembler.
+
+ <tag><htmlurl url="cc65.html" name="cc65.html"></tag>
+ Describes the cc65 C compiler.
+
+ <tag><htmlurl url="cl65.html" name="cl65.html"></tag>
+ Describes the cl65 compile & link utility.
+
+ <tag><htmlurl url="coding.txt" name="coding.txt"></tag>
+ Containes hints on creating the most effective code with cc65.
+
+ <tag><htmlurl url="compile.txt" name="compile.txt"></tag>
+ How to compile cc65 and the support tools.
+
+ <tag><htmlurl url="debugging.txt" name="debugging.txt"></tag>
+ Debug programs using the VICE emulator.
+
+ <tag><htmlurl url="geos.html" name="geos.html"></tag>
+ GEOSLib manual in several formats.
+
+ <tag><htmlurl url="grc.txt" name="grc.txt"></tag>
+ grc.txt - Describes the GEOS resource compiler (grc).
+
+ <tag><htmlurl url="index.html" name="index.html"></tag>
+ This file.
+
+ <tag><htmlurl url="internal.txt" name="internal.txt"></tag>
+ internal.doc - A somewhat older text describing several cc65 internals.
+
+ <tag><htmlurl url="intro.txt" name="intro.txt"></tag>
+ Describes the use of the tools by a short "hello world" example.
+
+ <tag><htmlurl url="ld65.html" name="ld65.html"></tag>
+ Describes the ld65 linker.
+
+ <tag><htmlurl url="library.html" name="library.html"></tag>
+ Describes the cc65 runtime and C libraries.
+
+ <tag><htmlurl url="newvers.txt" name="newvers.txt"></tag>
+ Somewhat outdated. Lists the differences between the current cc65 release
+ and the original atari version created by J.R Dunning.
+
+</descrip>
+
+</article>
+
+++ /dev/null
-
-
- Internals doc for CC65
-
-
-
-Stacks:
--------
-
-The program stack used by programs compiled with CC65 is located in high
-memory. The stack starts there and grows down. Arguments to functions, local
-data etc are allocated on this stack, and deallocated when functions exit.
-
-The program code and data is located in low memory. The heap is located
-between the program code and the stack. The default size for the parameter
-stack is 2K, you may change this by declaring an externally visible variable
-named named _stksize that holds the new stack size:
-
- unsigned _stksize = 4*1024; /* Use 4K stack */
-
-Note: The size of the stack is only needed if you use the heap, or if you
-call the stack checking routine (_stkcheck) from somewhere in your program.
-
-When calling other functions, the return address goes on the normal 6502
-stack, *not* on the parameter stack.
-
-
-
-Registers:
-----------
-
-Since CC65 is a member of the Small-C family of compilers, it uses the notion
-of a 'primary register'. In the CC65 implementation, I used the AX register
-pair as the primary register. Just about everything interesting that the
-library code does is done by somehow getting a value into AX, and then calling
-some routine or other. In places where Small-C would use a secondary
-register, top-of-stack is used, so for instance two argument function like
-integer-multiply work by loading AX, pushing it on the stack, loading the
-second value, and calling the internal function. The stack is popped, and the
-result comes back in AX.
-
-
-
-Calling sequences:
-------------------
-
-C functions are called by pushing their args on the stack, and JSR'ing to the
-entry point. (See ex 1, below) If the function returns a value, it comes back
-in AX. NOTE!!! A potentially significant difference between the CC65
-environment and other C environments is that the CALLEE pops arguments, not
-the CALLER. (This is done so as to generate more compact code) In normal use,
-this doesn't cause any problems, as the normal function entry/exit conventions
-take care of popping the right number of things off the stack, but you may
-have to worry about it when doing things like writing hand-coded assembly
-language routines that take variable numbers of arguments. More about that
-later.
-
-Ex 1: Function call: Assuming 'i' declared int and 'c' declared
- char, the following C code
-
- i = baz(i, c);
-
- in absence of a prototype generates this assembler code. I've added
- the comments.
-
- lda _i ; get 'i', low byte
- ldx _i+1 ; get 'i', hi byte
- jsr pushax ; push it
- lda _c ; get 'c'
- ldx #0 ; fill hi byte with 0
- jsr pushax ; push it
- ldy #4 ; arg size
- jsr _baz ; call the function
- sta _i ; store the result
- stx _i+1
-
- In presence of a prototype, the picture changes slightly, since the
- compiler is able to do some optimizations:
-
- lda _i ; get 'i', low byte
- ldx _i+1 ; get 'i', hi byte
- jsr pushax ; push it
- lda _c ; get 'c'
- jsr pusha ; push it
- jsr _baz ; call the function
- sta _i ; store the result
- stx _i+1
-
-
-Note that the two words of arguments to baz were popped before it exitted.
-The way baz could tell how much to pop was by the argument count in Y at call
-time. Thus, even if baz had been called with 3 args instead of the 2 it was
-expecting, that would not cause stack corruption.
-
-There's another tricky part about all this, though. Note that the args to baz
-are pushed in FORWARD order, ie the order they appear in the C statement.
-That means that if you call a function with a different number of args than it
-was expecting, they wont end up in the right places, ie if you call baz, as
-above, with 3 args, it'll operate on the LAST two, not the first two.
-
-
-
-Symbols:
---------
-
-CC65 does the usual trick of prepending an underbar ('_') to symbol names when
-compiling them into assembler. Therefore if you have a C function named
-'bar', CC65 will define and refer to it as '_bar'.
-
-
-
-Systems:
---------
-
-Supported systems at this time are: C64, C128, Plus/4, CBM 600/700, the newer
-PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to Kevin Ruland,
-who did the port).
-
-C64: The program runs in a memory configuration, where only the kernal ROM
- is enabled. The text screen is expected at the usual place ($400), so
- 50K of memory are available to the program.
-
-C128: The startup code will reprogram the MMU, so that only the kernal ROM
- is enabled. This means, there are 41K of memory available to the
- program.
-
-Plus/4: Unfortunately, the Plus/4 is not able to disable only part of it's
- ROM, it's an all or nothing approach. So, on the Plus/4, the program
- has only 28K available (16K machines are detected and the amount of
- free memory is reduced to 12K).
-
-CBM 600/700:
- The C program runs in a separate segment and has almost full 64K of
- memory available.
-
-PET: The startup code will adjust the upper memory limit to the installed
- memory. However, only linear memory is used, this limits the top to
- $8000, so on a 8032 or similar machine, 31K of memory are available to
- the program.
-
-APPLE2: The program starts at $800, end of RAM is $8E00, so 33.5K of memory
- (including stack) are available.
-
-Atari: The startup code will adjust the upper memory limit to the installed
- memory, considering future graphics memory usage (which is allocated
- at top of RAM). The programmer can specify which graphics mode is
- about to be used by defining a variable _graphmode_used, unsigned
- char, to the mode value (mode values like Atari DOS, 0-31).
- (Please note that graphics mode selection isn't supported in the
- Atari runtime lib yet!)
- In the default case the upper memory limit will be $8035 (with Basic
- cartridge) and $A035 (without cartridge). This is the default which
- leaves room for the biggest possible graphics mode. If only standard
- text mode is used (_graphmode_used = 0), the values are $9C1F (with
- Basic) and $BC1F (no cartridge).
- The program starts at $1F00 (to leave room for DOS), and the free
- memory values are $6135 (24K, Basic, default mode), $8135 (32K, no
- Basic, default mode), $7D1F (31K, Basic, mode 0) and $9D1F (39K,
- no Basic, mode 0).
- These values are for a 48K or 64K machine.
-
-Note: The above numbers do not mean that the remaining memory is unusable.
-However, it is not linear memory and must be accessed by other, nonportable
-methods. I'm thinking about a library extension that allows access to the
-additional memory as a far heap, but these routines do not exist until now.
-
-
-
-Inline Assembly:
-----------------
-
-CC65 allows inline assembly by a special keyword named "asm". Inline assembly
-looks like a function call. The string in parenthesis is output in the
-assembler file.
-
-Example, insert a break instruction into the code:
-
- asm ("\t.byte\t$00")
-
-Note: The \t in the string is replaced by the tab character, as in all other
-strings.
-
-Beware: Be careful when inserting inline code since this may collide with
-the work of the optimizer.
-
-
-
-Pseudo variables:
------------------
-
-There are two special variables available named __AX__ and __EAX__. These
-variables must never be declared (this gives an error), but may be used as any
-other variable. However, accessing these variables will access the primary
-register that is used by the compiler to evaluate expressions, return
-functions results and pass parameters.
-
-This feature is useful with inline assembly and macros. For example, a macro
-that reads a CRTC register may be written like this:
-
-#define wr(idx) (__AX__=(idx), \
- asm("\tsta\t$2000\n\tlda\t$2000\n\tldx\t#$00"), \
- __AX__)
-
--- /dev/null
+
+
+ Internals doc for CC65
+
+
+
+Stacks:
+-------
+
+The program stack used by programs compiled with CC65 is located in high
+memory. The stack starts there and grows down. Arguments to functions, local
+data etc are allocated on this stack, and deallocated when functions exit.
+
+The program code and data is located in low memory. The heap is located
+between the program code and the stack. The default size for the parameter
+stack is 2K, you may change this by declaring an externally visible variable
+named named _stksize that holds the new stack size:
+
+ unsigned _stksize = 4*1024; /* Use 4K stack */
+
+Note: The size of the stack is only needed if you use the heap, or if you
+call the stack checking routine (_stkcheck) from somewhere in your program.
+
+When calling other functions, the return address goes on the normal 6502
+stack, *not* on the parameter stack.
+
+
+
+Registers:
+----------
+
+Since CC65 is a member of the Small-C family of compilers, it uses the notion
+of a 'primary register'. In the CC65 implementation, I used the AX register
+pair as the primary register. Just about everything interesting that the
+library code does is done by somehow getting a value into AX, and then calling
+some routine or other. In places where Small-C would use a secondary
+register, top-of-stack is used, so for instance two argument function like
+integer-multiply work by loading AX, pushing it on the stack, loading the
+second value, and calling the internal function. The stack is popped, and the
+result comes back in AX.
+
+
+
+Calling sequences:
+------------------
+
+C functions are called by pushing their args on the stack, and JSR'ing to the
+entry point. (See ex 1, below) If the function returns a value, it comes back
+in AX. NOTE!!! A potentially significant difference between the CC65
+environment and other C environments is that the CALLEE pops arguments, not
+the CALLER. (This is done so as to generate more compact code) In normal use,
+this doesn't cause any problems, as the normal function entry/exit conventions
+take care of popping the right number of things off the stack, but you may
+have to worry about it when doing things like writing hand-coded assembly
+language routines that take variable numbers of arguments. More about that
+later.
+
+Ex 1: Function call: Assuming 'i' declared int and 'c' declared
+ char, the following C code
+
+ i = baz(i, c);
+
+ in absence of a prototype generates this assembler code. I've added
+ the comments.
+
+ lda _i ; get 'i', low byte
+ ldx _i+1 ; get 'i', hi byte
+ jsr pushax ; push it
+ lda _c ; get 'c'
+ ldx #0 ; fill hi byte with 0
+ jsr pushax ; push it
+ ldy #4 ; arg size
+ jsr _baz ; call the function
+ sta _i ; store the result
+ stx _i+1
+
+ In presence of a prototype, the picture changes slightly, since the
+ compiler is able to do some optimizations:
+
+ lda _i ; get 'i', low byte
+ ldx _i+1 ; get 'i', hi byte
+ jsr pushax ; push it
+ lda _c ; get 'c'
+ jsr pusha ; push it
+ jsr _baz ; call the function
+ sta _i ; store the result
+ stx _i+1
+
+
+Note that the two words of arguments to baz were popped before it exitted.
+The way baz could tell how much to pop was by the argument count in Y at call
+time. Thus, even if baz had been called with 3 args instead of the 2 it was
+expecting, that would not cause stack corruption.
+
+There's another tricky part about all this, though. Note that the args to baz
+are pushed in FORWARD order, ie the order they appear in the C statement.
+That means that if you call a function with a different number of args than it
+was expecting, they wont end up in the right places, ie if you call baz, as
+above, with 3 args, it'll operate on the LAST two, not the first two.
+
+
+
+Symbols:
+--------
+
+CC65 does the usual trick of prepending an underbar ('_') to symbol names when
+compiling them into assembler. Therefore if you have a C function named
+'bar', CC65 will define and refer to it as '_bar'.
+
+
+
+Systems:
+--------
+
+Supported systems at this time are: C64, C128, Plus/4, CBM 600/700, the newer
+PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to Kevin Ruland,
+who did the port).
+
+C64: The program runs in a memory configuration, where only the kernal ROM
+ is enabled. The text screen is expected at the usual place ($400), so
+ 50K of memory are available to the program.
+
+C128: The startup code will reprogram the MMU, so that only the kernal ROM
+ is enabled. This means, there are 41K of memory available to the
+ program.
+
+Plus/4: Unfortunately, the Plus/4 is not able to disable only part of it's
+ ROM, it's an all or nothing approach. So, on the Plus/4, the program
+ has only 28K available (16K machines are detected and the amount of
+ free memory is reduced to 12K).
+
+CBM 600/700:
+ The C program runs in a separate segment and has almost full 64K of
+ memory available.
+
+PET: The startup code will adjust the upper memory limit to the installed
+ memory. However, only linear memory is used, this limits the top to
+ $8000, so on a 8032 or similar machine, 31K of memory are available to
+ the program.
+
+APPLE2: The program starts at $800, end of RAM is $8E00, so 33.5K of memory
+ (including stack) are available.
+
+Atari: The startup code will adjust the upper memory limit to the installed
+ memory, considering future graphics memory usage (which is allocated
+ at top of RAM). The programmer can specify which graphics mode is
+ about to be used by defining a variable _graphmode_used, unsigned
+ char, to the mode value (mode values like Atari DOS, 0-31).
+ (Please note that graphics mode selection isn't supported in the
+ Atari runtime lib yet!)
+ In the default case the upper memory limit will be $8035 (with Basic
+ cartridge) and $A035 (without cartridge). This is the default which
+ leaves room for the biggest possible graphics mode. If only standard
+ text mode is used (_graphmode_used = 0), the values are $9C1F (with
+ Basic) and $BC1F (no cartridge).
+ The program starts at $1F00 (to leave room for DOS), and the free
+ memory values are $6135 (24K, Basic, default mode), $8135 (32K, no
+ Basic, default mode), $7D1F (31K, Basic, mode 0) and $9D1F (39K,
+ no Basic, mode 0).
+ These values are for a 48K or 64K machine.
+
+Note: The above numbers do not mean that the remaining memory is unusable.
+However, it is not linear memory and must be accessed by other, nonportable
+methods. I'm thinking about a library extension that allows access to the
+additional memory as a far heap, but these routines do not exist until now.
+
+
+
+Inline Assembly:
+----------------
+
+CC65 allows inline assembly by a special keyword named "asm". Inline assembly
+looks like a function call. The string in parenthesis is output in the
+assembler file.
+
+Example, insert a break instruction into the code:
+
+ asm ("\t.byte\t$00")
+
+Note: The \t in the string is replaced by the tab character, as in all other
+strings.
+
+Beware: Be careful when inserting inline code since this may collide with
+the work of the optimizer.
+
+
+
+Pseudo variables:
+-----------------
+
+There are two special variables available named __AX__ and __EAX__. These
+variables must never be declared (this gives an error), but may be used as any
+other variable. However, accessing these variables will access the primary
+register that is used by the compiler to evaluate expressions, return
+functions results and pass parameters.
+
+This feature is useful with inline assembly and macros. For example, a macro
+that reads a CRTC register may be written like this:
+
+#define wr(idx) (__AX__=(idx), \
+ asm("\tsta\t$2000\n\tlda\t$2000\n\tldx\t#$00"), \
+ __AX__)
+
--- /dev/null
+<!doctype linuxdoc system>
+
+<article>
+
+<title>cc65 Library Overview
+<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
+<date>02.12.2000
+
+<abstract>
+An overview over the runtime and C libraries that come with the cc65 compiler,
+including a discussion of the differences to the ISO standard.
+</abstract>
+
+<!-- Table of contents -->
+<toc>
+
+<!-- Begin the document -->
+
+<sect>Overview<p>
+
+This file contains a description of the library routines available for the
+cc65 C compiler. It is not complete in some areas, so if you miss something,
+have a look into the header files. All functions, that are not defined by the
+ISO C standard have a short comment in the headers, explaining their use.
+
+
+
+<sect>ISO C compatible library<p>
+
+The C library contains a large subset of the ISO C library. Functions are
+usually missing in areas, where there is no support on typical 6502 systems.
+Wide character sets are an example for this.
+
+I will not go into detail about the ISO functions. If a function is not
+mentioned here explicitly, expect it to be available and to behave as defined
+in the C standard.
+
+Functions that are NOT available:
+
+<itemize>
+
+ <item>ftell/fseek/fgetpos/fsetpos
+
+ <item>tmpfile/tmpnam
+
+ <item>The scanf family of functions
+
+ <item>time/asctime/ctime/difftime/asctime/gmtime/localtime/mktime/strftime
+
+ <item>system
+
+ <item>All functions that handle floating point numbers in some manner.
+
+ <item>The div and ldiv functions (because cc65 is not able to return
+ structs).
+
+ <item>All functions handling wide character strings.
+
+ <item>Signals and all related functions (having SIGSEGV would be cool:-)
+
+ <item>rename/remove/rewind
+
+ <item>setbuf/setvbuf/ungetc
+
+</itemize>
+
+Functions that are limited in any way:
+
+<itemize>
+
+ <item>fopen/fread/fwrite/fclose/fputs/fgets/fscanf....
+
+ These functions are built on open/read/write/close. Neither of these low
+ level functions is currently available for the supported systems, and so,
+ fopen and friends do not work. However, the functions exist and are tested
+ to some degree under the ACE operating systems (which is no longer
+ supported).
+
+
+ <item>The va_... family of macros
+
+ The macros do not work completely as defined by the standard. Since cc65 has
+ the wrong calling order, the (non-standard) va_fix macro must be used to
+ access fixed parameters in functions with a variable parameter size. See
+ newvers.txt for a discussion of the problem.
+
+ <item>strcspn/strpbrk/strspn
+
+ These functions have a length limitation of 256 for the second string
+ argument. Since this string gives a character set, and there are only 256
+ distinct characters, this shouldn't be a problem.
+
+ <item>getenv
+
+ Since there is no such thing as an environment on all supported systems, the
+ getenv function will always return a NULL pointer.
+
+
+ <item>locale
+
+ There is no other locale than the "C" locale. The native locale is identical
+ to the "C" locale.
+
+</itemize>
+
+
+In addition to these limitations, some more functions are limited if inlined
+versions are requested by using -Os:
+
+<itemize>
+
+ <item>The strlen function only works for strings with a maximum length of
+ 255 characters.
+
+ <item>The isxxx character classification functions from <tt/<ctype.h>/
+ will give unpredictable results if the argument is not in character range
+ (0..255). This limitation may be removed by #undef'ing the function name
+ (when using -Os, the functions are actually macros that expand to inline
+ assembler code, but the real functions are still available if the macro
+ definition is removed).
+
+</itemize>
+
+
+
+<sect>CPU specific stuff - 6502.h<p>
+
+The header file 6502.h contains some functions that make only sense with the
+6502 CPU. Examples are macros to insert more or less useful instructions into
+your C code, or a function to call arbitrary machine language subroutines,
+passing registers in and out.
+
+
+
+<sect>Target specific stuff<p>
+
+For each supported system there's a header file that contains calls or defines
+specific for this system. So, when programming for the C64, include c64.h, for
+the C128, include c128.h and so on. To make the task for the Commodore systems
+easier, there is also a header file named cbm.h that will define stuff common
+for all CBM systems, and include the header file for the specific target
+system.
+
+The header files contain
+
+<itemize>
+
+ <item>Defines for special keys (like function keys)
+
+ <item>Defines for special characters (like the graphics characters)
+
+ <item>Variables with a fixed address in memory that may be used to access
+ special hardware. For the C64 and C128 there is a variable struct named
+ <tt/SID/. Writing to the fields of this struct will write to the SID device
+ instead. Using these variables will make your program more readable and more
+ portable. Don't fear ineffective code when using these variables, the
+ compiler will translate reads and writes to these structs into direct memory
+ accesses.
+
+ <item>Other routines that make only sense for a specific system. One example
+ are routines to write memory locations in the system bank for the CBM
+ 600/700 family (called B128/B256 in the US).
+
+</itemize>
+
+
+<sect>Direct console I/O - <tt/conio.h/<p>
+
+The <tt/conio.h/ header file contains a large set of functions that do screen
+and keyboard I/O. The functions will write directly to the screen or poll the
+keyboard directly with no more help from the operating system than needed.
+This has some disadvantages, but on the other side it's fast and reasonably
+portable. conio implementations exist for the following targets:
+
+ <itemize>
+ <item>atari
+ <item>c64
+ <item>c128
+ <item>plus4
+ <item>cbm610 (all CBM series-II computers with 80 column video)
+ <item>pet (all CBM PET systems except the 2001)
+ <item>apple2
+ </itemize>
+
+The conio.h header file does also include the system specific header files
+which define constants for special characters and keys.
+
+
+
+<sect>Using the joystick - <tt/joystick.h/<p>
+
+For systems that have a joystick, <tt/joystick.h/ will define a subroutine to
+read the current value, including constants to evaluate the result of this
+function. To help in writing portable code, the header file will define the
+symbol <tt/__JOYSTICK__/ on systems that have a joystick.
+
+
+
+<sect>Using a mouse - <tt/mouse.h/<p>
+
+Some target machines support a mouse. Mouse support is currently in beta and
+available for the following targets:
+
+ <itemize>
+ <item>atari
+ <item>c64
+ </itemize>
+
+The available functions are declared in <tt/mouse.h/ To help writing portable
+code, the header file will define the symbol <tt/__MOUSE__/ in systems that
+support a mouse.
+
+
+<sect>Bugs/Feedback<p>
+
+If you have problems using the library, if you find any bugs, or if you're
+doing something interesting with it, I would be glad to hear from you. Feel
+free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
+name="uz@cc65.org">).
+
+
+
+<sect>Copyright<p>
+
+This C runtime library implementation for the cc65 compiler is (C)
+Copyright 1998-1999 Ullrich von Bassewitz. For usage of the binaries
+and/or sources the following conditions do apply:
+
+This software is provided 'as-is', without any expressed or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+<enum>
+<item> The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+<item> Altered source versions must be plainly marked as such, and must not
+ be misrepresented as being the original software.
+<item> This notice may not be removed or altered from any source
+ distribution.
+</enum>
+
+</article>
+
+
+
+++ /dev/null
-
-
- Description of the C library for the cc65 C compiler
-
- (C) Copyright 1998-1999 Ullrich von Bassewitz
- (uz@musoftware.de)
-
-
-
-Contents
---------
-
- 1. Overview
-
- 2. ISO C compatible library
-
- 3. CPU specific stuff - 6502.h
-
- 4. System specific stuff
-
- 5. Direct console I/O - conio.h
-
- 6. Using the joystick - joystick.h
-
- 7. Bugs/Feedback
-
- 8. Copyright
-
-
-
-1. Overview
------------
-
-This file contains a description of the library routines available for the
-cc65 C compiler. It is not complete in some areas, so if you miss
-something, have a look into the header files. All functions, that are not
-defined by the ISO C standard have a short comment in the headers,
-explaining their use.
-
-
-
-2. ISO C compatible library
----------------------------
-
-The C library contains a large subset of the ISO C library. Functions are
-usually missing in areas, where there is no support on typical 6502
-systems. Wide character sets are an example for this.
-
-I will not go into detail about the ISO functions. If a function is not
-mentioned here explicitly, expect it to be available and to behave as
-defined in the C standard.
-
-
-Functions that are NOT available:
-
- * ftell/fseek/fgetpos/fsetpos
-
- * tmpfile/tmpnam
-
- * The scanf family of functions
-
- * time/asctime/ctime/difftime/asctime/gmtime/localtime/mktime/strftime
-
- * system
-
- * All functions that handle floating point numbers in some manner.
-
- * The div and ldiv functions (because cc65 is not able to return
- structs).
-
- * All functions handling wide character strings.
-
- * Signals and all related functions (having SIGSEGV would be cool:-)
-
- * rename/remove/rewind
-
- * setbuf/setvbuf/ungetc
-
-
-
-Functions that are limited in any way:
-
- * fopen/fread/fwrite/fclose/fputs/fgets/fscanf....
-
- These functions are built on open/read/write/close. Neither of these
- low level functions is currently available for the supported systems,
- and so, fopen and friends do not work. However, the functions exist
- and are tested to some degree under the ACE operating systems (which
- is no longer supported).
-
-
- * The va_... family of macros
-
- The macros do not work completely as defined by the standard. Since cc65
- has the wrong calling order, the (non-standard) va_fix macro must be used
- to access fixed parameters in functions with a variable parameter size.
- See newvers.txt for a discussion of the problem.
-
-
- * strcspn/strpbrk/strspn
-
- These functions have a length limitation of 256 for the second string
- argument. Since this string gives a character set, and there are only 256
- distinct characters, this shouldn't be a problem.
-
-
- * Since there is no such thing as an environment on all supported
- systems, the getenv function will always return a NULL pointer.
-
-
- * There is no other locale than the "C" locale. The native locale is
- identical to the "C" locale.
-
-
-In addition to these limitations, some more functions are limited if inlined
-versions are requested by using -Os:
-
- * The strlen function only works for strings with a maximum length of
- 255 characters.
-
- * The isxxx character classification functions from <ctype.h> will give
- unpredictable results if the argument is not in character range
- (0..255). This limitation may be removed by #undef'ing the function
- name (when using -Os, the functions are actually macros that expand to
- inline assembler code, but the real functions are still available if
- the macro definition is removed).
-
-
-
-3. CPU specific stuff - 6502.h
-------------------------------
-
-The header file 6502.h contains some functions that make only sense with
-the 6502 CPU. Examples are macros to insert more or less useful
-instructions into your C code, or a function to call arbitrary machine
-language subroutines, passing registers in and out.
-
-
-
-4. System specific stuff
-------------------------
-
-For each supported system there's a header file that contains calls or
-defines specific for this system. So, when programming for the C64,
-include c64.h, for the C128, include c128.h and so on. To make the task
-for the Commodore systems easier, there is also a header file named cbm.h
-that will define stuff common for all CBM systems, and include the header
-file for the specific target system.
-
-The header files contain
-
- * Defines for special keys (like function keys)
-
- * Defines for special characters (like the graphics characters)
-
- * Variables with a fixed address in memory that may be used to access
- special hardware. For the C64 and C128 there is a variable struct
- named "sid". Writing to the fields of this struct will write to the
- SID device instead. Using these variables will make your program more
- readable and more portable. Don't fear ineffective code when using
- these variables, the compiler will translate reads and writes to these
- structs into direct memory accesses.
-
- * Other routines that make only sense for a specific system. One example
- are routines to write memory locations in the system bank for the CBM
- 600/700 family (called B128/B256 in the US).
-
-
-
-5. Direct console I/O - conio.h
--------------------------------
-
-The conio header file contains a large set of functions that do screen and
-keyboard I/O. The functions will write directly to the screen or poll the
-keyboard directly with no more help from the operating system than needed.
-This has some disadvantages, but on the other side it's fast and
-reasonably portable. conio implementations exist for the following
-targets:
-
- c64
- c128
- plus/4
- cbm610 (that is, the complete 600/700 series)
- pet (all PETs except the 2001)
- apple 2
- atari
-
-The conio.h header file does also include the system specific header files
-which define constants for special characters and keys.
-
-
-
-6. Using the joystick - joystick.h
-----------------------------------
-
-For systems that have a joystick, joystick.h will define a subroutine to
-read the current value, including constants to evaluate the result of this
-function. To help in writing portable code, the header file will define
-the symbol __JOYSTICK__ on systems that have a joystick.
-
-
-
-7. Bugs/Feedback
-----------------
-
-If you have problems using the library, if you find any bugs, or if you've
-written some extensions or otherwise interesting programs, I would be glad
-to hear from you. Feel free to contact me by email (uz@musoftware.de).
-
-
-
-8. Copyright
-------------
-
-This C runtime library implementation for the cc65 compiler is (C)
-Copyright 1998-1999 Ullrich von Bassewitz. For usage of the binaries
-and/or sources the following conditions do apply:
-
-This software is provided 'as-is', without any expressed or implied
-warranty. In no event will the authors be held liable for any damages
-arising from the use of this software.
-
-Permission is granted to anyone to use this software for any purpose,
-including commercial applications, and to alter it and redistribute it
-freely, subject to the following restrictions:
-
-1. The origin of this software must not be misrepresented; you must not
- claim that you wrote the original software. If you use this software
- in a product, an acknowledgment in the product documentation would be
- appreciated but is not required.
-2. Altered source versions must be plainly marked as such, and must not
- be misrepresented as being the original software.
-3. This notice may not be removed or altered from any source
- distribution.
-
-
-
-
-
+++ /dev/null
-
-Documentation overview:
-
-
- BUGS - Known compiler bugs.
-
- CREDITS - Who helped with the compiler and tools?
-
- ar65.txt - Describes the ar65 archiver.
-
- ca65.txt - Describes the ca65 macro assembler.
-
- cc65.txt - Describes the cc65 C compiler.
-
- cl65.txt - Describes the cl65 compile & link utility.
-
- coding.txt - Containes hints on creating the most effective code
- with cc65.
-
- compile.txt - How to compile cc65 and the support tools.
-
- debugging.txt - Debug programs using the VICE emulator.
-
- geos.* - GEOSLib manual in several formats.
-
- grc.txt - Describes the GEOS resource compiler (grc).
-
- internal.doc - A somewhat older text describing several cc65 internals.
-
- intro.txt - Describes the use of the tools by a short "hello world"
- example.
-
- ld65.txt - Describes the ld65 linker.
-
- library.txt - Describes the cc65 runtime and C libraries.
-
- newvers.txt - Somewhat outdated. Lists the differences between the
- current cc65 release and the original atari version
- created by J.R Dunning.
-
- readme.txt - This file.
-
-
projects / cc65 / commitdiff