--- wikisrc/ports/evbarm.mdwn	2018/11/21 13:27:04	1.57
+++ wikisrc/ports/evbarm.mdwn	2018/11/22 00:56:36	1.58
@@ -29,7 +29,7 @@ four main variables: the word size, the 
 endianness, and whether there is hardware floating point.  By default
 the CPU type is "earm", and this implies aarch32 (32-bit), \todo cpu
 architecture, little endian (el when explicitly stated), and soft
-(emulated) floating point.  Another example, suitable for Raspberry PI
+(Emulated) floating point.  Another example, suitable for Raspberry PI
 2, is earmv7hf, which is aarch32, the v7 instruction set, little
 endian, and hardware floating point.
 
@@ -46,6 +46,53 @@ sometimes referred to as a distinct port
 with code in src/sys/arch/aarch64, but it is built as the evbarm port
 with aarch64 cpu type, and available as the alias evbarm64.
 
+Note that MACHINE_ARCH=aarch64 currently refers to the A64 instruction
+set and the aarch64 architecture, built for the armv8 architecture.
+(Note also that armv8 is the first architecture to support aarch64, so
+this will not be an issue until at least armv9.)
+
+#### ABI types
+
+There are two basic ABIs on ARM.  One, called oabi, assumed a
+particular kind of hardware floating point (FPA).  This results in
+faulting any floating-point instructions for kernel emulation on a
+vast number of CPus, which is very slow.  A newer one, called eabi,
+has two variants.  Both have stricter alignment rules, tending to 8
+byte rather than 4 bytes for 8-byte types (but actually read the specs
+if you care).  The one without "hf" emulates floating point without
+causing traps/emulation, and "hf" uses VFP instructions, which are
+present on modern CPUs. See the
+[TS-7200](https://wiki.embeddedarm.com/wiki/EABI_vs_OABI) and
+[Debian](https://wiki.debian.org/ArmEabiPort) documentation.
+
+Now, EABI is normal, and OABI is crufty.  The only real reason NetBSD
+retains OABI support is binary compatibility with older releases.  The
+"arm" and "armeb" MACHINE_ARCH targets are OABI; the rest of the
+targets, all having "earm" are EABI.
+
+\todo CHECK THIS: The "aarch64" MACHINE_ARCH target is an EABI variant.
+
+### Relationship of MACHINE_ARCH to official ARM terminology
+
+Note that these are all little endian, and have big endian variants
+with a "eb" sufix.   
+
+[[!table data="""
+MACHINE_ARCH | 32/64 | ARM architecture version | ABI
+arm | 32 | ? | oabi
+earm | 32 | armv4 (effectively an alias) | eabi
+earmv4 | 32 | armv4 (no thumb, so ok on strongarm) | eabi
+earmv5 | 32 | armv5t | eabi
+earmv6 | 32 | armv6 | eabi
+earmv7 | 32 | armv7 | eabi
+aarch64 | 64 | armv8 | \todo ? eabi
+"""]]
+
+\todo Explain why, if we have armv4, and this is confusing, we still have earm as a MACHINE_ARCH.
+
+\todo Explain if MACHINE_ARCH values correspond to a particular
+argument to some CPU selection command in gcc (and/or clang).
+
 ### Kernels and userland
 
 The evbarm userland can be used on any system that can run code of the