From: cuz Date: Sun, 3 Dec 2000 17:00:40 +0000 (+0000) Subject: More SGML conversions, index page X-Git-Tag: V2.12.0~3011 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=0d2f5c0ab513a81aab8d0304e8f3f40b17c425ce;p=cc65 More SGML conversions, index page git-svn-id: svn://svn.cc65.org/cc65/trunk@529 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- diff --git a/doc/Makefile b/doc/Makefile index 0a419ebb2..289d816fd 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -10,7 +10,10 @@ SGML = ar65.sgml \ cc65.sgml \ cl65.sgml \ dio.sgml \ - ld65.sgml + geos.sgml \ + index.sgml \ + ld65.sgml \ + library.sgml TXT = $(SGML:.sgml=.txt) HTML = $(SGML:.sgml=.html) @@ -50,6 +53,10 @@ info: $(INFO) .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 *~ diff --git a/doc/index.sgml b/doc/index.sgml new file mode 100644 index 000000000..8d37aa7e4 --- /dev/null +++ b/doc/index.sgml @@ -0,0 +1,71 @@ + + +
+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> + diff --git a/doc/internal.doc b/doc/internal.doc deleted file mode 100644 index 2c2476f6a..000000000 --- a/doc/internal.doc +++ /dev/null @@ -1,203 +0,0 @@ - - - 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__) - diff --git a/doc/internal.txt b/doc/internal.txt new file mode 100644 index 000000000..2c2476f6a --- /dev/null +++ b/doc/internal.txt @@ -0,0 +1,203 @@ + + + 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__) + diff --git a/doc/library.sgml b/doc/library.sgml new file mode 100644 index 000000000..c3a6a65ce --- /dev/null +++ b/doc/library.sgml @@ -0,0 +1,251 @@ +<!doctype linuxdoc system> + +<article> + +<title>cc65 Library Overview +<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org"> +<date>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> + + + diff --git a/doc/library.txt b/doc/library.txt deleted file mode 100644 index 22c44fb25..000000000 --- a/doc/library.txt +++ /dev/null @@ -1,239 +0,0 @@ - - - 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. - - - - - diff --git a/doc/readme.txt b/doc/readme.txt deleted file mode 100644 index 6e35dd158..000000000 --- a/doc/readme.txt +++ /dev/null @@ -1,43 +0,0 @@ - -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. - -