Changed the documentation to reflect the new fastcall/cdecl reality.

diff --git a/doc/cc65.sgml b/doc/cc65.sgml
index a6b4a07eebbb701c4b206f6d713faff1e8dbdd09..bf7b1e336127d6ecba8f3a9aec97208791d3a18f 100644 (file)
--- a/doc/cc65.sgml
+++ b/doc/cc65.sgml
@@ -3,7 +3,7 @@
 <article>
 <title>cc65 Users Guide
 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
-<date>2000-09-03, 2001-10-02, 2005-08-01
+<date>2015-03-13
 
 <abstract>
 cc65 is a C compiler for 6502 targets. It supports several 6502 based home
@@ -549,9 +549,9 @@ and the one defined by the ISO standard:
         be passed as parameters by value. However, struct assignment *is*
        possible.
        <p>
-<item> Part of the C library is available only with fastcall calling
-       conventions (see below).  It means that you must not mix pointers to
-       those functions with pointers to user-written, not-fastcall functions.
+<item> Most of the C library is available only with the fastcall calling
+       convention (see below).  It means that you must not mix pointers to
+       those functions with pointers to user-written, cdecl functions.
        <p>
 <item> The <tt/volatile/ keyword doesn't have an effect. This is not as bad
         as it sounds, since the 6502 has so few registers that it isn't
@@ -589,29 +589,54 @@ This cc65 version has some extensions to the ISO C standard.
        <ref id="inline-asm" name="see there">.
        <p>
 
-<item> There is a special calling convention named "fastcall".
-       The syntax for a function declaration using fastcall is
+<item>  The normal calling convention -- for non-variadic functions -- is
+        named "fastcall". The syntax for a function declaration that
+        <em/explicitly/ uses fastcall is
+
+        <tscreen><verb>
+        &lt;return type&gt; fastcall &lt;function name&gt; (&lt;parameter list&gt;)
+        </verb></tscreen>
+        or
+        <tscreen><verb>
+        &lt;return type&gt; __fastcall__ &lt;function name&gt; (&lt;parameter list&gt;)
+        </verb></tscreen>
+        An example would be
+        <tscreen><verb>
+        void __fastcall__ f (unsigned char c)
+        </verb></tscreen>
+        The first form of the fastcall keyword is in the user namespace and can
+        therefore be disabled with the <tt><ref id="option--standard"
+        name="--standard"></tt> command line option.
 
-       <tscreen><verb>
-       &lt;return type&gt; fastcall &lt;function name&gt; (&lt;parameter list&gt;)
-       </verb></tscreen>
-       or
-       <tscreen><verb>
-               &lt;return type&gt; __fastcall__ &lt;function name&gt; (&lt;parameter list&gt;)
-       </verb></tscreen>
-       An example would be
-       <tscreen><verb>
-               void __fastcall__ f (unsigned char c)
-       </verb></tscreen>
-       The first form of the fastcall keyword is in the user namespace and can
-       therefore be disabled with the <tt><ref id="option--standard"
+        For functions that are <tt/fastcall/, the rightmost parameter is not
+        pushed on the stack but left in the primary register when the function
+        is called. That significantly reduces the cost of calling functions.
+        <p>
+
+<item>  There is another calling convention named "cdecl". Variadic functions
+        (their prototypes have an ellipsis [<tt/.../]) always use this
+        convention. The syntax for a function declaration using cdecl is
+
+        <tscreen><verb>
+        &lt;return type&gt; cdecl &lt;function name&gt; (&lt;parameter list&gt;)
+        </verb></tscreen>
+        or
+        <tscreen><verb>
+        &lt;return type&gt; __cdecl__ &lt;function name&gt; (&lt;parameter list&gt;)
+        </verb></tscreen>
+        An example would be
+        <tscreen><verb>
+        void __cdecl__ f (unsigned char c)
+        </verb></tscreen>
+        The first form of the cdecl keyword is in the user namespace and can
+        therefore be disabled with the <tt><ref id="option--standard"
         name="--standard"></tt> command line option.
 
-       For functions declared as <tt/fastcall/, the rightmost parameter is not
-       pushed on the stack but left in the primary register when the function
-       is called. This will reduce the cost when calling assembler functions
-       significantly, especially when the function itself is rather small.
-       <p>
+        For functions that are <tt/cdecl/, the rightmost parameter is pushed
+        onto the stack before the function is called. That increases the cost
+        of calling those functions, especially when they are called from many
+        places.
+        <p>
 
 <item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/.
        Both refer to the primary register that is used by the compiler to
@@ -663,7 +688,7 @@ This cc65 version has some extensions to the ISO C standard.
        </verb></tscreen>
 
        Since the variable is of type <tt/void/ you may not use it as is.
-       However, taking the address of the variable results in a <tt/void*/
+       However, taking the address of the variable results in a <tt/void */
        which may be passed to any function expecting a pointer.
 
        See the <url url="geos.html" name="GEOS library document"> for examples

diff --git a/doc/customizing.sgml b/doc/customizing.sgml
index 23cf8c5e8f68397a24a9dda5fb895ee2b543257d..a54821c348318de5e01aa6bfc16c7e57c55756dd 100644 (file)
--- a/doc/customizing.sgml
+++ b/doc/customizing.sgml
@@ -3,7 +3,7 @@
 <article>
 <title>Defining a Custom cc65 Target
 <author>Bruce Reidenbach
-<date>2010-02-22
+<date>2015-03-13
 
 <abstract>
 This section provides step-by-step instructions on how to use the cc65
@@ -525,15 +525,16 @@ The first step in creating the assembly language code for the driver is
 to determine how to pass the C arguments to the assembly language
 routine.  The cc65 toolset allows the user to specify whether the data
 is passed to a subroutine via the stack or by the processor registers by
-using the <tt>__fastcall__</tt> function declaration (note that there
-are two underscore characters in front of and two behind the
-<tt>fastcall</tt> declaration).  When <tt>__fastcall__</tt> is
-specified, the rightmost argument in the function call is passed to the
+using the <tt/__fastcall__/ and <tt/__cdecl__/ function qualifiers (note that
+there are two underscore characters in front of and two behind each
+qualifier).  <tt/__fastcall__/ is the default.  When <tt/__cdecl__/ <em/isn't/
+specified, and the function isn't variadic (i.e., its prototype doesn't have
+an ellipsis), the rightmost argument in the function call is passed to the
 subroutine using the 6502 registers instead of the stack.  Note that if
 there is only one argument in the function call, the execution overhead
 required by the stack interface routines is completely avoided.
 
-Without <tt>__fastcall__</tt>, the argument is loaded in the A and X
+With <tt/__cdecl__</tt>, the last argument is loaded into the A and X
 registers and then pushed onto the stack via a call to <tt>pushax</tt>.
 The first thing the subroutine does is retrieve the argument from the
 stack via a call to <tt>ldax0sp</tt>, which copies the values into the A
@@ -561,7 +562,7 @@ _foo:   jsr     ldax0sp    ;  Retrieve A and X from the stack
         jmp     incsp2     ;  Pop A and X from the stack (includes return)
 </verb></tscreen>
 
-If <tt>__fastcall__</tt> is specified, the argument is loaded into the A
+If <tt/__cdecl__/ isn't specified, then the argument is loaded into the A
 and X registers as before, but the subroutine is then called
 immediately.  The subroutine does not need to retrieve the argument
 since the value is already available in the A and X registers.
@@ -596,7 +597,7 @@ variable which is stored in the zero page memory space in order to allow
 for retrieval of each character in the string via the indirect indexed
 addressing mode.
 
-The assembly language routine is stored in a file names
+The assembly language routine is stored in a file named
 &quot;rs232_tx.s&quot; and is shown below:
 
 <tscreen><code>
@@ -680,7 +681,7 @@ all of the behind-the-scene work is transparent to the user.
 #define TX_FIFO_FULL  (FIFO_STATUS &amp; 0x01)
 #define RX_FIFO_EMPTY (FIFO_STATUS &amp; 0x02)
 
-extern void wait ();
+extern void wait (void);
 extern void __fastcall__ rs232_tx (char *str);
 
 int main () {