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.

The vmx example is based on:

On Mon, Apr 24, 2017 at 01:53:43AM -0700, Akihiro Suda wrote [8]:
> I think we should not take too much effort for deciding example
> values, but how about:
>
>   "feature `vmx` marks support for instruction
>   `VMXON,VMXOFF,VMLAUNCH,VMRESUME,VMCALL,VMPTRLD,VMPTRST,VMCLEAR,VMREAD
>   and VMWRITE`, and this image contains an executable compiled to
>   use `VM... instructions` with no fallback”.
>
> I see some reasons to deploy such VMs as OCI images:
>
> - Android emulator (x86)
> - Forked versions of KVM, that cannot be installed via apt-get
> - `docker run`-nable Unikernel demo https://github.com/Unikernel-Systems/DockerConEU2015-demo
> - ...
>
> For these use cases, checking whether `vmx` supported is useful,
> because `vmx` is typically missing on EC2.

[1]: opencontainers#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]: opencontainers#622 (comment)
[8]: opencontainers#631 (comment)

Signed-off-by: W. Trevor King <wking@tremily.us>

image-index.md

@@ -67,7 +67,13 @@ 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.
+        For example, include `vmx` (for `X86_FEATURE_VMX`) if the image contains an executable compiled to use `VMXON` and related instructions with no fallback.
+        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 and SHOULD be submitted to this specification for standardization.
 
 - **`annotations`** *string-string map*
 
@@ -99,8 +105,8 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
       "platform": {
         "architecture": "amd64",
         "os": "linux",
-        "os.features": [
-          "sse4"
+        "features": [
+          "fpu"
         ]
       }
     }
@@ -112,5 +118,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

schema/imageindex_test.go

@@ -61,7 +61,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "vmx"
         ]
       }
     }
@@ -84,7 +84,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "vmx"
         ]
       }
     }
@@ -128,7 +128,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "vmx"
         ]
       }
     }
@@ -152,7 +152,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "vmx"
         ]
       }
     }
@@ -185,7 +185,7 @@ func TestImageIndex(t *testing.T) {
         "architecture": "amd64",
         "os": "linux",
         "features": [
-          "sse4"
+          "vmx"
         ]
       }
     }

specs-go/v1/index.go

@@ -38,7 +38,7 @@ type Platform struct {
 	Variant string `json:"variant,omitempty"`
 
 	// Features is an optional field specifying an array of strings, each
-	// listing a required CPU feature (for example `sse4` or `aes`).
+	// listing a required CPU feature.
 	Features []string `json:"features,omitempty"`
 }