image-index: Document Linux cpuinfo flags (on x86) for platform.features

Based on Akihiro Suda's proposal [1] and the subsequent discussion.

Using the Linux kernel to define the values is very convenient on
Linux, but will likely be a pain for folks on other OSes.  If a
comprehensive, OS-agnostic list is found, we could use that instead,
but would want to provide a mapping from that list of values to the
Linux cpuinfo slugs for convenience.  Providing a mapping from the
OS-agnostic list to the cpuinfo analog on non-Linux OSes would also be
convenient.  Until then, folks wondering what a given feature slug
means but unwilling to dig through the Linux source may find the Stack
Overflow post at [2] useful.

This definition is not only Linux-centric, it is x86-centric.  The x86
Linux implementation writes 'flags' out here [3], but arm uses
'Features' [4].  While we could suggest values for other
architectures, this commit restricts itself to the x86 family (using
their GOARCH names [5], as the runtime spec recommends [6]), because
that's the scope Stephen is currently claiming [7].  Extending the
field to other architectures can happen in follow-up work.

[1]: #622 (comment)
[2]: http://unix.stackexchange.com/questions/43539/what-do-the-flags-in-proc-cpuinfo-mean
[3]: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/tree/arch/x86/kernel/cpu/proc.c?id=refs/tags/v4.10.4#n96
[4]: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/tree/arch/arm/kernel/setup.c?id=refs/tags/v4.10.4#n1234
[5]: https://golang.org/doc/install/source#environment
[6]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc5/config.md#platform
[7]: #622 (comment)

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

image-index.md

@@ -67,7 +67,12 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 
     - **`features`** *array of strings*
 
-        This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature (for example `sse4` or `aes`).
+        This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature.
+
+        When `architecture` is 386 or amd64 Image indexes SHOULD use, and implementations SHOULD understand, values [supported by Linux][cpufeatures.h] with the `X86_FEATURE_` prefix removed and the remainder lowercased (e.g. `fpu` for `X86_FEATURE_FPU` and `vme` for `X86_FEATURE_VME`).
+        On Linux on these architectures, the features supported by host CPUs can be found in the `flags` entries in the `cpuinfo` file provided by the [proc filesystem][proc.5].
+
+        When `architecture` is neither 386 nor amd64, values are implementation-defined.
 
 - **`annotations`** *string-string map*
 
@@ -112,5 +117,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 }
 ```
 
+[cpufeatures.h]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/x86/include/asm/cpufeatures.h
+[proc.5]: http://man7.org/linux/man-pages/man5/proc.5.html
 [runtime-platform2]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc3/config.md#platform
 [matrix]: media-types.md#compatibility-matrix