Merge pull request #151 from greg-king5/fastcall

[cc65] / doc / cc65.sgml

diff --git a/doc/cc65.sgml b/doc/cc65.sgml
index aa8a75aefcf0b806eef38679f04acd2790d040f4..9198d6982d1bc6b5ff91d1009195079c2fee4c84 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-05-26
 
 <abstract>
 cc65 is a C compiler for 6502 targets. It supports several 6502 based home
@@ -74,6 +74,7 @@ Short options:
 
 Long options:
   --add-source                  Include source as comment
+  --all-cdecl                   Make functions default to __cdecl__
   --bss-name seg                Set the name of the BSS segment
   --check-stack                 Generate stack overflow checks
   --code-name seg               Set the name of the CODE segment
@@ -114,6 +115,14 @@ Here is a description of all the command line options:
 
 <descrip>
 
+  <tag><tt>--all-cdecl</tt></tag>
+
+  Tells the compiler that functions which aren't declared explicitly with
+  either the <tt/__cdecl__/ or <tt/__fastcall__/ calling conventions should
+  have the cdecl convention.  (Normally, functions that aren't variadic are
+  fast-called.)
+
+
   <label id="option-bss-name">
   <tag><tt>--bss-name seg</tt></tag>
 
@@ -550,9 +559,10 @@ 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 with only the fastcall calling
+       convention (<ref id="extension-fastcall" name="see below">).  It means
+       that you must not mix pointers to those functions with pointers to
+       user-written, cdecl functions (the calling conventions are incompatible).
        <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
@@ -590,30 +600,58 @@ 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
+<label id="extension-fastcall">
+<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;)
+       &lt;return type&gt; __fastcall__ &lt;function name&gt; (&lt;parameter list&gt;)
        </verb></tscreen>
-       An example would be
+       An example is
        <tscreen><verb>
-               void __fastcall__ f (unsigned char c)
+       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.
 
-       For functions declared as <tt/fastcall/, the rightmost parameter is not
+       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. This will reduce the cost when calling assembler functions
-       significantly, especially when the function itself is rather small.
+       is called. That significantly reduces the cost of calling those functions.
+       <newline><newline>
        <p>
 
+<item>  There is another calling convention named "cdecl". Variadic functions
+        (their prototypes have an ellipsis &lsqb;<tt/.../&rsqb;) always use that
+        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 is
+        <tscreen><verb>
+        int* __cdecl__ f (unsigned char c)
+        </verb></tscreen>
+
+        The first form of the cdecl keyword is in the user namespace;
+        and therefore, can be disabled with the <tt/<ref id="option--standard"
+        name="--standard">/ command-line option.
+
+        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.<newline><newline>
+        <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
        evaluate expressions or return function results. <tt/__AX__/ is of