Add a reference for Arm CPU features in docs

This previously existed in the form of a spreadsheet I'd made, but
export it in a form that's accessible from the repository.

The spreadsheet is much prettier, with rowspan and colspan used
liberally, but Markdown doesn't support this, and GoB's Markdown
renderer does not seem to allow HTML tables.

Change-Id: I5833f828b994af4907b4ce1e17a2c42adb664800
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/87607
Auto-Submit: David Benjamin <davidben@google.com>
Reviewed-by: Lily Chen <chlily@google.com>
Commit-Queue: Lily Chen <chlily@google.com>

docs/arm_features.md

diff --git a/docs/arm_features.md b/docs/arm_features.md
new file mode 100644
index 0000000..5d05ece
--- /dev/null
+++ b/docs/arm_features.md
@@ -0,0 +1,29 @@
+# Arm Cryptography Features
+
+Arm cryptography features are a bit of a zoo. This table is available as a
+reference.
+
+| Feature | Armv8.0 | Armv8.2 | ID_AA64ISAR0_EL1 | Arm C Language Extensions | Arm C Language Extensions (old) | GCC/LLVM targets | GCC/LLVM targets (old) | getauxval | Windows |
+|---|---|---|---|---|---|---|---|---|---|
+| FEAT_AES | Cryptography Extension | AES functionality | none / AES / AES+PMULL | __ARM_FEATURE_AES | __ARM_FEATURE_CRYPTO | aes | crypto | HWCAP_AES | PF_ARM_V8_CRYPTO_INSTRUCTIONS_AVAILABLE |
+| FEAT_PMULL | Cryptography Extension | AES functionality | none / AES / AES+PMULL | __ARM_FEATURE_AES | __ARM_FEATURE_CRYPTO | aes | crypto | HWCAP_PMULL | PF_ARM_V8_CRYPTO_INSTRUCTIONS_AVAILABLE |
+| FEAT_SHA1 | Cryptography Extension | SHA-1 and SHA-256 functionality | none / SHA1 | __ARM_FEATURE_SHA2 | __ARM_FEATURE_CRYPTO | sha2 | crypto | HWCAP_SHA1 | PF_ARM_V8_CRYPTO_INSTRUCTIONS_AVAILABLE |
+| FEAT_SHA256 | Cryptography Extension | SHA-1 and SHA-256 functionality | none / SHA256 / SHA256+SHA512 | __ARM_FEATURE_SHA2 | __ARM_FEATURE_CRYPTO | sha2 | crypto | HWCAP_SHA256 | PF_ARM_V8_CRYPTO_INSTRUCTIONS_AVAILABLE |
+| FEAT_SHA512 | | SHA-512 instructions | none / SHA256 / SHA256+SHA512 | __ARM_FEATURE_SHA512 | | sha3 | | HWCAP_SHA512 | PF_ARM_SHA512_INSTRUCTIONS_AVAILABLE |
+| FEAT_SHA3 | | SHA-3 instructions | none / SHA3 | __ARM_FEATURE_SHA3 | | sha3 | | HWCAP_SHA3 | PF_ARM_SHA3_INSTRUCTIONS_AVAILABLE |
+
+## Footnotes
+
+* The Arm reference manual refers to `FEAT_*` names but they don't appear to actually be used in the ISA anywhere.
+
+* Armv8.0 considered all four initial cryptography features as one extension.
+
+* Armv8.2 now says the original four features can be implemented separately in groups of two. That carried over into various `crypto` features splitting into `aes` and `sha2`. (But note `aes` in this formulation includes `FEAT_PMULL` and `sha2` includes `FEAT_SHA1`.)
+
+* `ID_AA64ISAR0_EL1` is Arm's CPUID equivalent. It is a collection of four-bit fields. They tend to group features together. E.g. in the "AES" field, 0b0000 = none, 0b0001 = AES, 0b0010 = AES+PMULL. This means, for example, it is not possible to meaningfully implement `FEAT_PMULL` without `FEAT_AES`.
+
+* GCC/LLVM targets refer to strings used in places like `-march=armv8-a+aes` or `__attribute__((target("aes")))`.
+
+* `__ARM_FEATURE_SHA2` is not a typo. "SHA2" in ACLE includes SHA-1 but not SHA-512.
+
+* The `sha3` GCC/LLVM target is also not a typo. `sha3` includes SHA-512, despite the preprocessor macros being finer-grained. There is no `sha512` GCC/LLVM target.