10 The program stack used by programs compiled with CC65 is located in high
11 memory. The stack starts there and grows down. Arguments to functions, local
12 data etc are allocated on this stack, and deallocated when functions exit.
14 The program code and data is located in low memory. The heap is located
15 between the program code and the stack. The default size for the parameter
16 stack is 2K, you may change this by declaring an externally visible variable
17 named named _stksize that holds the new stack size:
19 unsigned _stksize = 4*1024; /* Use 4K stack */
21 Note: The size of the stack is only needed if you use the heap, or if you
22 call the stack checking routine (_stkcheck) from somewhere in your program.
24 When calling other functions, the return address goes on the normal 6502
25 stack, *not* on the parameter stack.
32 Since CC65 is a member of the Small-C family of compilers, it uses the notion
33 of a 'primary register'. In the CC65 implementation, I used the AX register
34 pair as the primary register. Just about everything interesting that the
35 library code does is done by somehow getting a value into AX, and then calling
36 some routine or other. In places where Small-C would use a secondary
37 register, top-of-stack is used, so for instance two argument function like
38 integer-multiply work by loading AX, pushing it on the stack, loading the
39 second value, and calling the internal function. The stack is popped, and the
40 result comes back in AX.
47 C functions are called by pushing their args on the stack, and JSR'ing to the
48 entry point. (See ex 1, below) If the function returns a value, it comes back
49 in AX. NOTE!!! A potentially significant difference between the CC65
50 environment and other C environments is that the CALLEE pops arguments, not
51 the CALLER. (This is done so as to generate more compact code) In normal use,
52 this doesn't cause any problems, as the normal function entry/exit conventions
53 take care of popping the right number of things off the stack, but you may
54 have to worry about it when doing things like writing hand-coded assembly
55 language routines that take variable numbers of arguments. More about that
58 Ex 1: Function call: Assuming 'i' declared int and 'c' declared
59 char, the following C code
63 in absence of a prototype generates this assembler code. I've added
66 lda _i ; get 'i', low byte
67 ldx _i+1 ; get 'i', hi byte
70 ldx #0 ; fill hi byte with 0
73 jsr _baz ; call the function
74 sta _i ; store the result
77 In presence of a prototype, the picture changes slightly, since the
78 compiler is able to do some optimizations:
80 lda _i ; get 'i', low byte
81 ldx _i+1 ; get 'i', hi byte
85 jsr _baz ; call the function
86 sta _i ; store the result
90 Note that the two words of arguments to baz were popped before it exitted.
91 The way baz could tell how much to pop was by the argument count in Y at call
92 time. Thus, even if baz had been called with 3 args instead of the 2 it was
93 expecting, that would not cause stack corruption.
95 There's another tricky part about all this, though. Note that the args to baz
96 are pushed in FORWARD order, ie the order they appear in the C statement.
97 That means that if you call a function with a different number of args than it
98 was expecting, they wont end up in the right places, ie if you call baz, as
99 above, with 3 args, it'll operate on the LAST two, not the first two.
106 CC65 does the usual trick of prepending an underbar ('_') to symbol names when
107 compiling them into assembler. Therefore if you have a C function named
108 'bar', CC65 will define and refer to it as '_bar'.
115 Supported systems at this time are: C64, C128, Plus/4, CBM 600/700, the newer
116 PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to Kevin Ruland,
119 C64: The program runs in a memory configuration, where only the kernal ROM
120 is enabled. The text screen is expected at the usual place ($400), so
121 50K of memory are available to the program.
123 C128: The startup code will reprogram the MMU, so that only the kernal ROM
124 is enabled. This means, there are 41K of memory available to the
127 Plus/4: Unfortunately, the Plus/4 is not able to disable only part of it's
128 ROM, it's an all or nothing approach. So, on the Plus/4, the program
129 has only 28K available (16K machines are detected and the amount of
130 free memory is reduced to 12K).
133 The C program runs in a separate segment and has almost full 64K of
136 PET: The startup code will adjust the upper memory limit to the installed
137 memory. However, only linear memory is used, this limits the top to
138 $8000, so on a 8032 or similar machine, 31K of memory are available to
141 APPLE2: The program starts at $800, end of RAM is $8E00, so 33.5K of memory
142 (including stack) are available.
144 Atari: The startup code will adjust the upper memory limit to the installed
145 memory, considering future graphics memory usage (which is allocated
146 at top of RAM). The programmer can specify which graphics mode is
147 about to be used by defining a variable _graphmode_used, unsigned
148 char, to the mode value (mode values like Atari DOS, 0-31).
149 (Please note that graphics mode selection isn't supported in the
150 Atari runtime lib yet!)
151 In the default case the upper memory limit will be $8035 (with Basic
152 cartridge) and $A035 (without cartridge). This is the default which
153 leaves room for the biggest possible graphics mode. If only standard
154 text mode is used (_graphmode_used = 0), the values are $9C1F (with
155 Basic) and $BC1F (no cartridge).
156 The program starts at $1F00 (to leave room for DOS), and the free
157 memory values are $6135 (24K, Basic, default mode), $8135 (32K, no
158 Basic, default mode), $7D1F (31K, Basic, mode 0) and $9D1F (39K,
160 These values are for a 48K or 64K machine.
162 Note: The above numbers do not mean that the remaining memory is unusable.
163 However, it is not linear memory and must be accessed by other, nonportable
164 methods. I'm thinking about a library extension that allows access to the
165 additional memory as a far heap, but these routines do not exist until now.
172 CC65 allows inline assembly by a special keyword named "asm". Inline assembly
173 looks like a function call. The string in parenthesis is output in the
176 Example, insert a break instruction into the code:
180 Note: The \t in the string is replaced by the tab character, as in all other
183 Beware: Be careful when inserting inline code since this may collide with
184 the work of the optimizer.
191 There are two special variables available named __AX__ and __EAX__. These
192 variables must never be declared (this gives an error), but may be used as any
193 other variable. However, accessing these variables will access the primary
194 register that is used by the compiler to evaluate expressions, return
195 functions results and pass parameters.
197 This feature is useful with inline assembly and macros. For example, a macro
198 that reads a CRTC register may be written like this:
200 #define wr(idx) (__AX__=(idx), \
201 asm("\tsta\t$2000\n\tlda\t$2000\n\tldx\t#$00"), \