improve definition of `platform.features`

[AkihiroSuda]

https://github.com/opencontainers/image-spec/blob/ab461b048bd1c8b6077d8e96936f706a518233c2/image-index.md

This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature (for example sse4 or aes).

The definition of platform.features seems vague.
At first glance, I thought the values are adopted from Linux /proc/cpuinfo, but I learned that the cpuinfo file never contains sse4.

http://unix.stackexchange.com/questions/43539/what-do-the-flags-in-proc-cpuinfo-mean

Intel-defined CPU features, CPUID level 0x00000001 (ecx)

• sse4_1: SSE-4.1
• sse4_2: SSE-4.2

More extended AMD flags: CPUID level 0x80000001, ecx

• sse4a: SSE-4A

(Note: AMD's SSE-4A is completely unrelated to Intel's SSE4 http://www.cpu-world.com/Glossary/S/SSE4a.html)

How about improving the definition like this:

---

This OPTIONAL property specifies an array of strings, each specifying a mandatory CPU feature.

Values for features SHOULD use, and implementations SHOULD understand, flags entries listed in the Linux /proc/cpuinfo file. If an architecture is not supported by Linux, it SHOULD be submitted to this specification for standardization.
For example, sse4_1 or aes on the amd64 and i386 architecture.

Also, for compatibility with Docker images, implementations SHOULD understand the following features values as well:

Architecture	Docker-compatible value	OCI standard value
amd64, i386	sse4	sse4_1

[jonboulle]

Proposed wording SGTM

[wking]

On Tue, Mar 21, 2017 at 04:05:09AM -0700, Jonathan Boulle wrote: Proposed wording SGTM

And to me, although I think we want: If a feature is not supported by Linux… instead of: If an architecture is not supported by Linux… if the idea is to have folks registering things like ‘sse4_2’. And I'd be happier if cpuinfo's flags values were documented somewhere, but I haven't been able to turn up docs yet.

[wking]

flags entries listed in the Linux /proc/cpuinfo file.

Unfortunately, flags turns out to be an x86-ism. The x86 code writes it out here, but other arches may do different things. For example, arm uses Features. The best docs I've found so far are in an SO post, which is probably quickly stale and not a good idea as a spec reference ;).

So I'm not sure what to do. Using flags (or Features, etc.) is certainly convenient on Linux, but “dig through the Linux source to find valid values” isn't particularly friendly for validation maintainers, non-Linux implementation maintainers, or non-Linux config authors. On the other hand, the current guidance isn't really helping anyone, so a Linux-x86-specific fix may be an improvement.

[stevvooe]

@AkihiroSuda I think you are getting hung up on the examples. If the examples are wrong fix them. There is no "docker compatible" value -- they aren't really in use.

For the most part, these feature flags are platform dependent.

[AkihiroSuda]

Thank you all for the feedback.

What should we do toward v1.0?

Plan 1. Mark the platform.features "reserved" for future releases. Implementations SHOULD NOT use this field in v1.0.

Plan 2. Just remove it. We can revive it in future releases if needed.

Plan 3. Standardize it for Linux on well-known platforms

My suggestion is 1 (or 2).

Also, the same discussion could be applied to platform.os.version, platform.os.features and platform.variant, perhaps:

os.version string
This OPTIONAL property specifies the operating system version, for example 10.0.10586.

os.features array of strings
This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature (for example on Windows win32k).

variant string
This OPTIONAL property specifies the variant of the CPU, for example armv6l to specify a particular CPU variant of the ARM CPU.

cc @RobDolinMS @jstarks @jhowardmsft

[AkihiroSuda]

Can we set milestone of this to 1.0.0-rc6?

[stevvooe]

platform.features is for x86 CPU features that are required for the image. If other architectures want to use it for specific meanings, there is not reason it couldn't be re-purposed here.

If someone wants to step up and do the work here, that would be great.

[wking]

If someone wants to step up and do the work here, that would be great.

There's not much work to do if we agree that scoping the definition to Linux/(386|amd64) is acceptable for now. In #631, I've taken a stab based on @AkihiroSuda's initial proposal with the following changes:

• Mention that flags is specific to the x86 family.
• Drop the Docker-compat table.
• Limit the definition to the x86 family.

I'm also comfortable with @AkihiroSuda's plans 1 or 2, but your response suggests you prefer his plan 3, which is where I've tried to go with #631.

[RobDolinMS]

@AkihiroSuda Would you want to convert this to a pull request?

[RobDolinMS]

@stevvooe suggested earlier in the discussion that this could be milestone==v1.0.0-rc6. Would one of the @opencontainers/image-spec-maintainers want to set as such?