From ca8c1fdd0a035c4ebb9d99099db688bc5d3b6728 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 30 Mar 2017 21:23:27 -0700 Subject: [PATCH] image-index: Document Linux cpuinfo flags (on x86) for platform.features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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]: https://github.com/opencontainers/image-spec/issues/622#issue-215629652 [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]: https://github.com/opencontainers/image-spec/issues/622#issuecomment-290521269 [8]: https://github.com/opencontainers/image-spec/pull/631#issuecomment-296583316 Signed-off-by: W. Trevor King --- image-index.md | 14 +++++++++++--- schema/imageindex_test.go | 10 +++++----- specs-go/v1/index.go | 2 +- 3 files changed, 17 insertions(+), 9 deletions(-) diff --git a/image-index.md b/image-index.md index c85fd47b8..26835e823 100644 --- a/image-index.md +++ b/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": [ + "vmx" ] } } @@ -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 diff --git a/schema/imageindex_test.go b/schema/imageindex_test.go index 69d1a1fa0..37d33255e 100644 --- a/schema/imageindex_test.go +++ b/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" ] } } diff --git a/specs-go/v1/index.go b/specs-go/v1/index.go index c7d56ef66..0c8a35828 100644 --- a/specs-go/v1/index.go +++ b/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"` }