--- wikisrc/ports/evbarm.mdwn	2018/11/07 14:33:50	1.51
+++ wikisrc/ports/evbarm.mdwn	2018/11/22 00:56:36	1.58
@@ -22,21 +22,76 @@ Matt Thomas is the maintainer of NetBSD/
 
 ### CPU types
 
-The evbarm port can be built with a variety of CPU options.  There are
-three main variables: the instruction set, the endianness, and whether
-there is hardware floating point.  By default the CPU type is "earm",
-and this implies little endian (el when explicitly stated), and soft
-(emulated) floating point.  Another example, suitable for Raspberry PI
-2, is earmv7hf, which is the v7 instruction set, little endian,
-and hardware floating point.
+The evbarm port can be built with a variety of CPU options, corresponding to the
+[large array of ARM CPU architectures](https://en.wikipedia.org/wiki/ARM_architecture#Cores).
+There are
+four main variables: the word size, the instruction set, 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
+2, is earmv7hf, which is aarch32, the v7 instruction set, little
+endian, and hardware floating point.
 
 Typically, various boards are best compiled with a CPU type that
 matches the board's CPU and floating point support, but generally a
 lower CPU instruction set version is workable on a newer board.  See
 build.sh and look for aliases for the evbarm port.
 
-Some processors can operate as arm or the 64-bit ARM variant, aarch64, which is supported by
-[[NetBSD/aarch64|aarch64]].
+Through NetBSD 8, the evbarm port has supported exclusively the
+aarch32 (32-bit CPU) sub-family of the ARM architecture.  Some
+processors, such as many supporting the armv8 CPU architecture, also
+support a 64-bit instruction set, referred to as aarch64.  This is
+sometimes referred to as a distinct port, [[NetBSD/aarch64|aarch64]],
+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
 
@@ -46,9 +101,11 @@ kernel for that board.
 
 ### anita and qemu
 
-anita can be used to test builds.  evbarm-earmv7hf uses "qemu -M
-vexpress-a15" and evbarm-aarch64 uses "qemu -M virt".  (Information on
-how to test emulated versions of other specific hardware is welcome.)
+anita can be used to test builds.  (In addition to anita, install qemu and dtb-arm-vexpress from pkgsrc.)   The release subdirectory should follow the naming convention on the autobuild cluster, used below.
+
+ - evbarm-earmv7hf uses "qemu-system-arm -M vexpress-a15"
+ - evbarm-aarch64 uses "qemu-system-aarch64 -M virt"
+ - Information on how to test emulated versions of other specific hardware is welcome.
 
 ### Board specific information
  - [[Allwinner sunxi family SoCs|Allwinner]]