1 files changed, 161 insertions, 0 deletions
diff --git a/doc/supplements/c4x/callconv.t b/doc/supplements/c4x/callconv.t
new file mode 100644
index 0000000000..94d52a05a3
--- /dev/null
+++ b/doc/supplements/c4x/callconv.t
@@ -0,0 +1,161 @@
+@c
+@c  COPYRIGHT (c) 1988-1999.
+@c  On-Line Applications Research Corporation (OAR).
+@c  All rights reserved.
+@c
+@c  $Id$
+@c
+
+@chapter Calling Conventions
+
+@section Introduction
+
+Each high-level language compiler generates
+subroutine entry and exit code based upon a set of rules known
+as the compiler's calling convention.   These rules address the
+following issues:
+
+@itemize @bullet
+@item register preservation and usage
+@item parameter passing
+@item call and return mechanism
+@end itemize
+
+A compiler's calling convention is of importance when
+interfacing to subroutines written in another language either
+assembly or high-level.  Even when the high-level language and
+target processor are the same, different compilers may use
+different calling conventions.  As a result, calling conventions
+are both processor and compiler dependent.
+
+The GNU Compiler Suite follows the same calling conventions
+as the Texas Instruments toolset.
+
+@section Processor Background
+
+The TI C3x and C4x processors support a simple yet
+effective call and return mechanism.  A subroutine is invoked
+via the branch to subroutine (@code{XXX}) or the jump to subroutine
+(@code{XXX}) instructions.  These instructions push the return address
+on the current stack.  The return from subroutine (@code{XXX})
+instruction pops the return address off the current stack and
+transfers control to that instruction.  It is important to
+note that the call and return mechanism for the C3x/C4x does not
+automatically save or restore any registers.  It is the
+responsibility of the high-level language compiler to define the
+register preservation and usage convention.
+
+XXX other supplements may have "is is".
+
+@section Calling Mechanism
+
+All subroutines are invoked using either a @code{XXX}
+or @code{XXX} instruction and return to the user application via the
+@code{XXX} instruction.
+
+@section Register Usage
+
+XXX
+
+As discussed above, the @code{XXX} and @code{XXX} instructions do
+not automatically save any registers.  Subroutines use the registers
+@b{D0}, @b{D1}, @b{A0}, and @b{A1} as scratch registers.  These registers are
+not preserved by subroutines therefore, the contents of
+these registers should not be assumed upon return from any subroutine
+call including but not limited to an RTEMS directive.
+
+The GNU and Texas Instruments compilers follow the same conventions
+for register usage.
+
+@section Parameter Passing
+
+Both the GNU and Texas Instruments compilers support two conventions
+for passing parameters to subroutines.  Arguments may be passed in
+memory on the stack or in registers.
+
+@subsection Parameters Passed in Memory
+
+When passing parameters on the stack, the calling convention assumes
+that arguments are placed on the current stack before the subroutine
+is invoked via the @code{XXX} instruction.  The first argument is
+assumed to be closest to the return address on the stack.  This means
+that the first argument of the C calling sequence is pushed last.  The
+following pseudo-code illustrates the typical sequence used to call a
+subroutine with three (3) arguments:
+
+@example
+@group
+push third argument
+push second argument
+push first argument
+invoke subroutine
+remove arguments from the stack
+@end group
+@end example
+
+The arguments to RTEMS are typically pushed onto the
+stack using a @code{sti} instruction with a pre-incremented stack
+pointer as the destination.  These arguments must be removed
+from the stack after control is returned to the caller.  This
+removal is typically accomplished by subtracting the size of the
+argument list in words from the current stack pointer.
+
+@c XXX XXX instruction .. XXX should be code format.
+
+With the GNU Compiler Suite, parameter passing via the 
+stack is selected by invoking the compiler with the
+@code{-mmemparm XXX} argument.  This argument must be
+included when linking the application in order to
+ensure that support libraries also compiled assuming
+parameter passing via the stack are used.  The default
+parameter passing mechanism is XXX.
+
+When this parameter passing mecahanism is selected, the @code{XXX}
+symbol is predefined by the C and C++ compilers
+and the @code{XXX} symbol is predefined by the assembler.
+This behavior is the same for the GNU and Texas Instruments
+toolsets.  RTEMS uses these predefines to determine how
+parameters are passed in to those C3x/C4x specific routines
+that were written in assembly language.
+
+@subsection Parameters Passed in Registers
+
+When passing parameters via registers, the calling convention assumes
+that the arguments are placed in particular registers based upon
+their position and data type before the subroutine is invoked via
+the @code{XXX} instruction.  
+
+The following pseudo-code illustrates
+the typical sequence used to call a subroutine with three (3) arguments:
+
+@example
+@group
+move third argument to XXX
+move second argument to XXX
+move first argument to XXX
+invoke subroutine
+@end group
+@end example
+
+With the GNU Compiler Suite, parameter passing via 
+registers is selected by invoking the compiler with the
+@code{-mregparm XXX} argument.  This argument must be
+included when linking the application in order to
+ensure that support libraries also compiled assuming
+parameter passing via the stack are used.  The default
+parameter passing mechanism is XXX.
+
+When this parameter passing mecahanism is selected, the @code{XXX}
+symbol is predefined by the C and C++ compilers
+and the @code{XXX} symbol is predefined by the assembler.
+This behavior is the same for the GNU and Texas Instruments
+toolsets.  RTEMS uses these predefines to determine how
+parameters are passed in to those C3x/C4x specific routines
+that were written in assembly language.
+
+@section User-Provided Routines
+
+All user-provided routines invoked by RTEMS, such as
+user extensions, device drivers, and MPCI routines, must also
+adhere to these calling conventions.
+