Vulkan-docs: Extension compatibility & provisional

[krOoze]

So the styleguide says an extension is always fully compatible (except historical accidents). So extensions cannot ever add commands to themselves.

But VkExtensionProperties::specVersion says they are backwards-compatible.

And "Provisional" entry says those may break backwards compatibility.

1) That info should be unified.
2) I am not clear on NVX. I think it used to mean (as KHX) the same as provisional? Should NVX extensions be marked provisional? (in separate #808 as suggested)

[oddhack]

I'll bring this up internally. We have experimented with different answers and evolved our definitions over time, so it's not surprising there are some internal inconsistencies.

NVX is a question for NVIDIA. I suggest bringing that up separately and pinging @jeffbolznv @pdaniell-nv to get it on their radar.

[oddhack]

Trying to close this out, and figure out where the language currently stands.

• VkExtensionProperties says specVersion is "incremented with backward compatible changes". Saying it's incremented with all meaningful changes captures provisional extensions as well.
• The boilerplate-provisional-header section says they may not be backwards compatible.
• The style guide says that "extensions in general are strictly additive and backward-compatible" which does cover provisional extensions, without calling them out explicitly.
• The style guide needs to add a required pluralization and spelling of "backward(s)(-)compatible" as that isn't consistent (side issue).

Is there anything else you think still needs doing here, or would that one change to VkExtensionProperties cover it?

[krOoze]

Lets see. Reviewing extension docs:

---

Implementations must not advertise any pair of extensions that cannot be enabled together due to behavioral differences, or any extension that cannot be enabled against the advertised version.

but

Due to some slight behavioral differences, this extension must not be enabled alongside VK_KHR_maintenance1, or in an instance created with version 1.1 or later requested in VkApplicationInfo::apiVersion.

and but

• ppEnabledExtensionNames must not contain VK_AMD_negative_viewport_height
• ppEnabledExtensionNames must not contain both VK_KHR_buffer_device_address and VK_EXT_buffer_device_address

Little bit of mixed message. Will the impl not advertise these, or is the app responsible not to enable them.

---

The extensions supported by a layer may also change between two calls, e.g. if the layer implementation is replaced by a different version between those calls.

That is bit of a double-bind problem. I cannot be sure which version of extension I have enabled. And assuming extensions are not required to be fully-compatible across revisions, I must avoid using functionality in new revision.

---

This section is marked as informal as there is no binding responsibility on implementations of the Vulkan API - these guarantees are however a contract between the Vulkan Working Group and developers using this Specification.

tf does that even mean? Quantum superposition of being normative and not normative at the same time?

This probably needs to say it is normative, but it does address specification writers (i.e. neither impl, nor app). In the end, it does have an impact on applications, which need to consider this when requesting versions.

Anyway, strangely the Compatibility Guarantees chapter seems to say nothing about the compatibility of extension revisions, which is weird.

---

• specVersion is the version of this extension. It is an integer, incremented with backward compatible changes.

bit odd place to introduce crucial information

and

New functionality may be added to Vulkan via either new extensions or new versions of the core, or new versions of an extension in some cases.

alright

Extensions in general are strictly additive and backwards-compatible with each other and with the core API. However, as described in more detail the Fundamentals chapter of the Vulkan API Specification, explicit incompatibilities may exist, and must be documented.

Not sure what the link refers to in the Fundamentals chapter.
Anyway, we are getting bit of a mess of several kinds of compatibility. Compatibility with the app (across extension revisions), compatibility with other extensions, compatibility with Vulkan version, source compatibility, binary compatibility...

oh wait:

The revision value indicates a patch version of the extension specification, and differences in this version number maintain full compatibility, as defined in the Compatibility Guarantees section of the Vulkan API Specification.

but that was already violated few times.

Besides the revision numbers go back into some internal pre-release revisions, which definitely change things. (In future extensions should be released with revision number 1. For old extensions the release revision number should perhaps be documented.)

---

Some vendors may use an alternate author ID ending in X for some of their extensions. The exact meaning of such an author ID is defined by each vendor, and may not be equivalent to KHX, but it is likely to indicate a lesser degree of interface stability than a non-X extension from the same vendor.

hm, ok

The functionality defined by such extensions may change in ways that break backwards compatibility between revisions, and before final release of a non-provisional version of that extension.

ok, but above it was said the versions are backward compatible.

Anyway this is about fourth attempt at making some system to experimental extensions, And it lacks consistency; the VK_NVX extensions are not marked provisional, which means that theoretically they should be backwards compatible across revisions which they are not.

---

Extensions with higher numbers may have dependencies upon extensions with lower numbers, and must define any relevant interactions with lower-numbered extensions.

however

A multi-vendor extension should be able to be enabled alongside any KHR extension or other multi-vendor extension, and for any minor or patch version of the core Specification beyond the minimum version it requires. A vendor extension should be able to be enabled alongside any KHR extension, multi-vendor extension, or other vendor extension from the same vendor, and for any minor or patch version of the core Specification beyond the minimum version it requires. A vendor extension may be able to be enabled alongside vendor extensions from another vendor.

implies interactions might not be defined

A KHR extension must be able to be enabled alongside any other KHR extension, and for any minor or patch version of the core Specification beyond the minimum version it requires.

does this apply to provisional too?

---

Generally the information feels bit spread out. Basically I would expect singular well-written "Extending Vulkan" chapter that has everything.

[polarina]

Extensions must be registered with Khronos
For extensions which add to the Vulkan API, including definitions of those additions to vk.xml.

but

Extension structures are not described in the base Vulkan Specification, but either in layered Specifications incorporating those extensions, or in separate vendor-provided documents.

I believe the intent here is that all extensions must be defined in vk.xml, but the semantics of said extension may not need be specified as part of the official specification.

[krOoze]

I guess so.
Bit offtopic issue as well, but while reading all the relevant docs, I might as well list anything that striked me as odd there...

[oddhack]

I believe the intent here is that all extensions must be defined in vk.xml, but the semantics of said extension may not need be specified as part of the official specification.

Any language talking about vendor extensions is aspirational. Conformance only applies to specifications that Khronos ratifies. That said, vendors and groups who develop EXT extensions generally play very well with Khronos.

[oddhack]

Generally the information feels bit spread out. Basically I would expect singular well-written "Extending Vulkan" chapter that has everything.

So, while I appreciate that you did a really thorough reading of everything with some relation to "extension" above, there's so much stuff in this single message that nobody in Khronos is likely to take time to try and address all of it. Yes, there are minor inconsistencies between what certain extensions actually do and what the spec says they should do. Yes, we don't have a great solution for non-finished functionality that still needs to be exposed in drivers, yet; hopefully provisional extensions will work better than prior attempts. Yes, vendors do weird things sometimes that we can't control (see previous message). All this and more is true.

But please try and focus down to a scope of things we can actually hope to make progress on. This issue started off relatively simple, and now my attempt to make progress on it just had about 4x as much additional material added on top. So it's likely to just go back and sit for another couple of years, because issues that aren't actually causing ISVs to complain pointedly are relatively low priority.

If we could go back to what I suggested, see if that addresses the originally posed issue, fix that, and then pick up some of these points individually, that would be more likely to complete in finite time.

[krOoze]

@oddhack Nobody said it is simple. And unwholistic fix always tends to break two things while only correcting one. Extensions are a relatively simple concept. If their descriptions in docs are unmaintainable, then that is an Issue in of itself.

That being said, here you go. Per OP:

Styleguide says an extension is always fully compatible:

The revision value indicates a patch version of the extension specification, and* differences in this version number maintain full compatibility*, as defined in the Compatibility Guarantees section of the Vulkan API Specification.

Compatibility Guarantee does not really say anything I can find on the matter. The spec otherwisely says:

specVersion is the version of this extension. It is an integer, incremented with backward compatible changes.