From dc5e4a09c077096214fd9223b688f709781e0e9c 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 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]: 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 Signed-off-by: W. Trevor King --- image-index.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/image-index.md b/image-index.md index c85fd47b8..977aa804d 100644 --- a/image-index.md +++ b/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