*** empty log message ***

1 files changed, 97 insertions, 0 deletions

diff --git a/doc/isa_abi_headache b/doc/isa_abi_headache
new file mode 100644
index 000000000..55621ca96
--- /dev/null
+++ b/doc/isa_abi_headache
@@ -0,0 +1,97 @@
+Terms Used In This Document:
+  ISA = Instruction Set Architecture.   The instructions the current
+        processor provides.
+  ABI = Application Binary Interface.  Specifies calling convention,
+        type sizes, etc.
+  AR64 = Arithmetic operations are 64-bit using 64-bit instructions
+	 (E.g., addition, subtraction, load, store, of 64-bit integer types
+	 are done with single instructions, not 32 bits at a time.)
+  Environment = The operating system and compiler.
+
+GMP is a very complex packagde to build since its speed is very
+sensitive to the ISA and ABI.  For example, if the ISA provides 64-bit
+instructions, it is crucial that GMP is configured to use them.
+
+Most environments that run on a 64-bit ISA provide more than one ABI.
+Typically one of the supported ABI's is a backward compatible 32-bit
+ABI, and one ABI provides 64-bit addressing and `long' (sometimes
+known as LP64).  But a few environments (IRIX, HP-UX) provide
+intermediate ABI's using 32-bit addressing but allow efficient 64-bit
+operations through a `long long' type.  For the latter to be useful to
+GMP, the ABI must allow operations using the native 64-bit
+instructions provided by the ISA, and allow passing of 64-bit
+quantities atomically.
+
+The ABI is typically chosen by means of command line options to the
+compiler tools (gcc, cc, c89, nm, ar, ld, as).  Different environments
+use different defaults, but as of this writing (May 2000) the
+dominating default is to the plain 32-bit ABI in its most arcane form.
+
+The GMP 3.0.x approach was to compile using the ABI that gives the
+best performance.  That places the burden on users to pass special
+options to the compiler when they compile their GMP applications.
+That approach has its advantages and disadvantages.  The main
+advantage is that users don't unknowingly get bad GMP performance.
+The main disadvantage is that users' compiles (actually links) will
+fail unless they pass special compiler options.
+
+** SPARC
+
+System vendors often confuse ABI, ISA, and implementation.  The worst
+case is Solaris, were the unbundled compiler confuses ISA and ABI, and
+the options have very confusing names.
+
+     option		interpretation
+     ======		==============
+cc   -xarch=v8plus	ISA=sparcv9, ABI=V8plus (PTR=32, see below)
+gcc  -mv8plus		ISA=sparcv9, ABI=V8plus (see below)
+cc   -xarch=v9		ISA=sparcv9, ABI=V9 (implying AR=64, PTR=64)
+
+It's hard to believe, but the option v8plus really means ISA=V9!
+
+Solaris releases prior to version 7 running on a V9 CPU fails to
+save/restore the upper 32 bits of the `i' and `l' registers.  The
+`v8plus' option generates code that use as many V9 features as
+possible under such circumstances.
+
+** MIPS
+
+The IRIX 6 compilers gets things right.  They have a clear
+understanding of the differences between ABI and ISA.  The option
+names are descriptive.
+
+     option		interpretation
+     ======		==============
+cc   -n32		ABI=n32 (implying AR=64, PTR=32)
+gcc  -mabi=n32		ABI=n32 (implying AR=64, PTR=32)
+cc   -64		ABI=64 (implying AR=64, PTR=64)
+gcc  -mabi=64		ABI=64 (implying AR=64, PTR=64)
+cc   -mips3		ISA=mips3
+gcc  -mips3		ISA=mips3
+cc   -mips4		ISA=mips4
+gcc  -mips4		ISA=mips4
+
+** HP-PA
+
+HP-UX is somewhat weird, but not as broken as Solaris.
+
+     option		interpretation
+     ======		==============
+cc   +DA2.0		ABI=32bit (implying AR=64, PTR=32)
+cc   +DD64		ABI=64bit (implying AR=64, PTR=64)
+
+Code performing 64-bit arithmetic in the HP-UX 32-bit is not
+compatible with the 64-bit ABI; the former has a calling convention
+that passes/returns 64-bit integer quantities as two 32-bit chunks.
+
+** PowerPC
+
+While the PowerPC ABI's are capable of supporting 64-bit
+registers/operations, the compilers under AIX are similar to Solaris'
+cc in that they don't currently provide any 32-bit addressing with
+64-bit arithmetic.
+
+     option			interpretation
+     ======			==============
+cc   -q64			ABI=64bit (implying AR=64, PTR=64)
+gcc  -maix64 -mpowerpc64	ABI=64bit (implying AR=64, PTR=64)