Merge pull request #663 from IrgendwerA8/more_popptr1_adaptations

[cc65] / doc / cc65.sgml

diff --git a/doc/cc65.sgml b/doc/cc65.sgml
index 653a917dbf744cbf903f4b58f0d813bc14f4f331..11a5937b2cbf788c55d042fc2b0980bbe8c5017e 100644 (file)
--- a/doc/cc65.sgml
+++ b/doc/cc65.sgml
@@ -4,7 +4,7 @@
 <title>cc65 Users Guide
 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
 <url url="mailto:gregdk@users.sf.net" name="Greg King">
-<date>2017-03-21
+<date>2017-05-20
 
 <abstract>
 cc65 is a C compiler for 6502 targets. It supports several 6502 based home
@@ -407,6 +407,7 @@ Here is a description of all the command line options:
   <item>sim6502
   <item>sim65c02
   <item>supervision
+  <item>telestrat
   <item>vic20
   </itemize>
 
@@ -491,7 +492,8 @@ Here is a description of all the command line options:
   Using <tt/-Os/ will allow the compiler to inline some standard functions
   from the C library like strlen.  This will not only remove the overhead
   for a function call, but will make the code visible for the optimizer.
-  See also <tt/<ref id="option-inline-stdfuncs" name="--inline-stdfuncs">/.
+  See also the <tt/<ref id="option-inline-stdfuncs" name="--inline-stdfuncs">/
+  command line option.
 
   It is possible to concatenate the modifiers for <tt/-O/. For example, to
   enable register variables and inlining of standard functions, you may use
@@ -940,6 +942,10 @@ The compiler defines several macros at startup:
 
   This macro is defined if the target is the Supervision (-t supervision).
 
+  <tag><tt>__TELESTRAT__</tt></tag>
+
+  This macro is defined if the target is the Telestrat (-t telestrat).
+  
   <tag><tt>__TIME__</tt></tag>
 
   This macro expands to the time of translation of the preprocessing
@@ -1098,7 +1104,7 @@ parameter with the <tt/#pragma/.
   Allow the compiler to inline some standard functions from the C library like
   strlen.  If the argument is "off", inlining is disabled, otherwise it is enabled.
 
-  See also the the <tt/<ref id="option-inline-stdfuncs" name="--inline-stdfuncs">/
+  See also the <tt/<ref id="option-inline-stdfuncs" name="--inline-stdfuncs">/
   command line option.
 
   The <tt/#pragma/ understands the push and pop parameters as explained above.
@@ -1118,6 +1124,23 @@ parameter with the <tt/#pragma/.
   remembered and output as a whole when translation is finished.
 
 
+<sect1><tt>#pragma message (&lt;message&gt;)</tt><label id="pragma-message"><p>
+
+  This pragma is used to display informational messages at compile-time.
+
+  The message intented to be displayed must be a string literal.
+
+  Example:
+  <tscreen><verb>
+        #pragma message ("in a bottle")
+  </verb></tscreen>
+
+  Results in the compiler outputting the following to stderr:
+  <tscreen><verb>
+        example.c(42): Note: in a bottle
+  </verb></tscreen>
+
+
 <sect1><tt>#pragma optimize ([push,] on|off)</tt><label id="pragma-optimize"><p>
 
   Switch optimization on or off. If the argument is "off", optimization is
@@ -1228,6 +1251,39 @@ parameter with the <tt/#pragma/.
   </verb></tscreen>
 
 
+<sect1><tt>#pragma wrapped-call (push, &lt;name&gt;, &lt;identifier&gt;)</tt><label id="pragma-wrapped-call"><p>
+
+  This pragma sets a wrapper for functions, often used for trampolines.
+
+  The name is a function returning <tt/void/, and taking no parameters.
+  It must preserve the CPU's <tt/A/ and <tt/X/ registers if it wraps any
+  <tt/__fastcall__/ functions that have parameters.  It must preserve
+  the <tt/Y/ register if it wraps any variadic functions (they have "<tt/.../"
+  in their prototypes).
+
+  The identifier is an 8-bit number that's set into <tt/tmp4/.
+
+  The address of a wrapped function is passed in <tt/ptr4/.  The wrapper can
+  call that function by using "<tt/jsr callptr4/".
+
+  This feature is useful, for example, with banked memory, to switch banks
+  automatically to where a wrapped function resides, and then to restore the
+  previous bank when it returns.
+
+  The <tt/#pragma/ requires the push or pop argument as explained above.
+
+  Example:
+  <tscreen><verb>
+/* Note that this code can be in a header. */
+void mytrampoline(void); /* Doesn't corrupt __AX__ */
+
+#pragma wrapped-call (push, mytrampoline, 5)
+void somefunc1(void);
+void somefunc2(int, char *);
+#pragma wrapped-call (pop)
+  </verb></tscreen>
+
+
 <sect1><tt>#pragma writable-strings ([push,] on|off)</tt><label id="pragma-writable-strings"><p>
 
   Changes the storage location of string literals. For historical reasons,