git.sur5r.net Git - cc65/blob - doc/internal.txt

   1
   2
   3                             Internals doc for CC65
   4
   5
   6
   7 Stacks:
   8 -------
   9
  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.
  13
  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
  17 configuration.
  18
  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.
  21
  22 When calling other functions, the return address goes on the normal 6502
  23 stack, *not* on the parameter stack.
  24
  25
  26
  27 Registers:
  28 ----------
  29
  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.
  39
  40
  41
  42 Calling sequences:
  43 ------------------
  44
  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
  54 later.
  55
  56 Ex 1:  Function call:  Assuming 'i' declared int and 'c' declared
  57        char, the following C code
  58
  59         i = baz(i, c);
  60
  61        in absence of a prototype generates this assembler code.  I've added
  62        the comments.
  63
  64         lda     _i              ; get 'i', low byte
  65         ldx     _i+1            ; get 'i', hi byte
  66         jsr     pushax          ; push it
  67         lda     _c              ; get 'c'
  68         ldx     #0              ; fill hi byte with 0
  69         jsr     pushax          ; push it
  70         ldy     #4              ; arg size
  71         jsr     _baz            ; call the function
  72         sta     _i              ; store the result
  73         stx     _i+1
  74
  75        In presence of a prototype, the picture changes slightly, since the
  76        compiler is able to do some optimizations:
  77
  78         lda     _i              ; get 'i', low byte
  79         ldx     _i+1            ; get 'i', hi byte
  80         jsr     pushax          ; push it
  81         lda     _c              ; get 'c'
  82         jsr     pusha           ; push it
  83         jsr     _baz            ; call the function
  84         sta     _i              ; store the result
  85         stx     _i+1
  86
  87
  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.
  92
  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.
  98
  99
 100
 101 Symbols:
 102 --------
 103
 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'.
 107
 108
 109
 110 Systems:
 111 --------
 112
 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).
 116
 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.
 125
 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.
 129
 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
 132         program.
 133
 134 Plus/4: Unfortunately, the Plus/4 is not able to disable only part of it's
 135         ROM, it's an all or nothing approach. So, on the Plus/4, the program
 136         has only 28K available (16K machines are detected and the amount of
 137         free memory is reduced to 12K).
 138
 139 CBM 500:
 140         The C program runs in bank #0 and has a total of 48K memory available.
 141         This is less than what is available on its bigger brothers (CBM
 142         600/700) because the character data and video RAM is placed in the
 143         execution bank (#0) to allow the use of sprites.
 144
 145 CBM 600/700:
 146         The C program runs in a separate segment and has almost full 64K of
 147         memory available.
 148
 149 PET:    The startup code will adjust the upper memory limit to the installed
 150         memory. However, only linear memory is used, this limits the top to
 151         $8000, so on a 8032 or similar machine, 31K of memory are available to
 152         the program.
 153
 154 APPLE2: The program starts at $800, end of RAM is $8E00, so 33.5K of memory
 155         (including stack) are available.
 156
 157 Atari:  The startup code will adjust the upper memory limit to the installed
 158         memory, considering future graphics memory usage (which is allocated
 159         at top of RAM). The programmer can specify which graphics mode is
 160         about to be used by defining a variable _graphmode_used, unsigned
 161         char, to the mode value (mode values like Atari DOS, 0-31).
 162         (Please note that graphics mode selection isn't supported in the
 163         Atari runtime lib yet!)
 164         In the default case the upper memory limit will be $8035 (with Basic
 165         cartridge) and $A035 (without cartridge). This is the default which
 166         leaves room for the biggest possible graphics mode. If only standard
 167         text mode is used (_graphmode_used = 0), the values are $9C1F (with
 168         Basic) and $BC1F (no cartridge).
 169         The program starts at $1F00 (to leave room for DOS), and the free
 170         memory values are $6135 (24K, Basic, default mode), $8135 (32K, no
 171         Basic, default mode), $7D1F (31K, Basic, mode 0) and $9D1F (39K,
 172         no Basic, mode 0).
 173         These values are for a 48K or 64K machine.
 174
 175 Note: The above numbers do not mean that the remaining memory is unusable.
 176 However, it is not linear memory and must be accessed by other, nonportable
 177 methods. I'm thinking about a library extension that allows access to the
 178 additional memory as a far heap, but these routines do not exist until now.
 179
 180
 181
 182 Inline Assembly:
 183 ----------------
 184
 185 CC65 allows inline assembly by a special keyword named "asm". Inline assembly
 186 looks like a function call. The string in parenthesis is output in the
 187 assembler file.
 188
 189 Example, insert a break instruction into the code:
 190
 191         asm ("brk")
 192
 193 Beware: Be careful when inserting inline code since this may collide with
 194 the work of the optimizer.
 195
 196
 197
 198 Pseudo variables:
 199 -----------------
 200
 201 There are two special variables available named __AX__ and __EAX__. These
 202 variables must never be declared (this gives an error), but may be used as any
 203 other variable. However, accessing these variables will access the primary
 204 register that is used by the compiler to evaluate expressions, return
 205 functions results and pass parameters.
 206
 207 This feature is useful with inline assembly and macros. For example, a macro
 208 that reads a CRTC register may be written like this:
 209
 210 #define wr(idx) (__AX__=(idx),          \
 211                 asm ("sta $2000"),      \
 212                 asm ("lda $2000"),      \
 213                 asm ("ldx #$00"),       \
 214                 __AX__)
 215