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 for most platforms in the linker
19 Note: The size of the stack is only needed if you use the heap, or if you
20 call the stack checking routine (_stkcheck) from somewhere in your program.
22 When calling other functions, the return address goes on the normal 6502
23 stack, *not* on the parameter stack.
30 Since CC65 is a member of the Small-C family of compilers, it uses the notion
31 of a 'primary register'. In the CC65 implementation, I used the AX register
32 pair as the primary register. Just about everything interesting that the
33 library code does is done by somehow getting a value into AX, and then calling
34 some routine or other. In places where Small-C would use a secondary
35 register, top-of-stack is used, so for instance two argument function like
36 integer-multiply work by loading AX, pushing it on the stack, loading the
37 second value, and calling the internal function. The stack is popped, and the
38 result comes back in AX.
45 C functions are called by pushing their args on the stack, and JSR'ing to the
46 entry point. (See ex 1, below) If the function returns a value, it comes back
47 in AX. NOTE!!! A potentially significant difference between the CC65
48 environment and other C environments is that the CALLEE pops arguments, not
49 the CALLER. (This is done so as to generate more compact code) In normal use,
50 this doesn't cause any problems, as the normal function entry/exit conventions
51 take care of popping the right number of things off the stack, but you may
52 have to worry about it when doing things like writing hand-coded assembly
53 language routines that take variable numbers of arguments. More about that
56 Ex 1: Function call: Assuming 'i' declared int and 'c' declared
57 char, the following C code
61 in absence of a prototype generates this assembler code. I've added
64 lda _i ; get 'i', low byte
65 ldx _i+1 ; get 'i', hi byte
68 ldx #0 ; fill hi byte with 0
71 jsr _baz ; call the function
72 sta _i ; store the result
75 In presence of a prototype, the picture changes slightly, since the
76 compiler is able to do some optimizations:
78 lda _i ; get 'i', low byte
79 ldx _i+1 ; get 'i', hi byte
83 jsr _baz ; call the function
84 sta _i ; store the result
88 Note that the two words of arguments to baz were popped before it exitted.
89 The way baz could tell how much to pop was by the argument count in Y at call
90 time. Thus, even if baz had been called with 3 args instead of the 2 it was
91 expecting, that would not cause stack corruption.
93 There's another tricky part about all this, though. Note that the args to baz
94 are pushed in FORWARD order, ie the order they appear in the C statement.
95 That means that if you call a function with a different number of args than it
96 was expecting, they wont end up in the right places, ie if you call baz, as
97 above, with 3 args, it'll operate on the LAST two, not the first two.
104 CC65 does the usual trick of prepending an underbar ('_') to symbol names when
105 compiling them into assembler. Therefore if you have a C function named
106 'bar', CC65 will define and refer to it as '_bar'.
113 Supported systems at this time are: C64, C128, Plus/4, CBM 500, CBM 600/700,
114 the newer PET machines (not 2001), Atari 8bit, and the Apple ][ (thanks to
115 Kevin Ruland, who did the port).
117 C16: Works with unexpanded or memory expanded C16 and C116 machines.
118 However, a maximum of 32KB from the total memory is used. The Plus/4
119 target supports up to 64K of memory, but has a small code overhead
120 because of the banking routines involved. Apart from this additional
121 overhead, the Plus/4 target and the C16 target are the same. 16K
122 machines (unexpanded C16) have 12K of memory for C programs available,
123 machines with 32K or more have 28K available. The actual amount of
124 memory is auto detected.
126 C64: The program runs in a memory configuration, where only the kernal ROM
127 is enabled. The text screen is expected at the usual place ($400), so
128 50K of memory are available to the program.
130 C128: The startup code will reprogram the MMU, so that only the kernal ROM
131 is enabled. This means, there are 41K of memory available to the
134 Plus/4: Works with bank switching so 59K of memory are available to the
138 The C program runs in bank #0 and has a total of 48K memory available.
139 This is less than what is available on its bigger brothers (CBM
140 600/700) because the character data and video RAM is placed in the
141 execution bank (#0) to allow the use of sprites.
144 The C program runs in a separate segment and has almost full 64K of
147 PET: The startup code will adjust the upper memory limit to the installed
148 memory. However, only linear memory is used, this limits the top to
149 $8000, so on a 8032 or similar machine, 31K of memory are available to
153 The program starts at $803, end of RAM is $95FF, so 35.5K of memory
154 (including stack) are available to the program.
156 Atari: The startup code will adjust the upper memory limit to the installed
157 memory detected at runtime. The programmer can adjust the upper memory
158 limit by setting the __RESERVED_MEMORY__ variable at link time. The
159 given __RESERVED_MEMORY__ value will be subtracted from the upper
160 memory limit used by the runtine. This memory could be used as graphics
162 In the default case (no setting of __RESERVED_MEMORY__) the upper
163 memory limit is $9C1F (with Basic cartridge) and $BC1F (without
164 cartridge). The program starts at $2E00 by default.
165 These values are for a 48K or 64K machine.
167 Note: The above numbers do not mean that the remaining memory is unusable.
168 However, it is not linear memory and must be accessed by other, nonportable
169 methods. I'm thinking about a library extension that allows access to the
170 additional memory as a far heap, but these routines do not exist until now.
177 CC65 allows inline assembly by a special keyword named "asm". Inline assembly
178 looks like a function call. The string in parenthesis is output in the
181 Example, insert a break instruction into the code:
185 Beware: Be careful when inserting inline code since this may collide with
186 the work of the optimizer.
193 There are two special variables available named __AX__ and __EAX__. These
194 variables must never be declared (this gives an error), but may be used as any
195 other variable. However, accessing these variables will access the primary
196 register that is used by the compiler to evaluate expressions, return
197 functions results and pass parameters.
199 This feature is useful with inline assembly and macros. For example, a macro
200 that reads a CRTC register may be written like this:
202 #define wr(idx) (__AX__=(idx), \