Proposal for versioning the NonSemantic.Shader.DebugInfo Instruction Set

[dnovillo]

The SPIRV working group is currently discussing changes to the NonSemantic.Shader.Debuginfo.100 (NSDI.100) instruction set. To support this, we need to introduce a formal versioning system to the NSDI spec. This will affect how the instruction set is imported into SPIR-V modules and will have downstream effects on tooling.

The core idea is to follow the same versioning scheme used by Clspv Reflection.

1. Versioned imports: The import instruction will now specify a version, replacing the current hardcoded 100: %1 = OpExtInstImport "NonSemantic.Shader.DebugInfo.<ver>.
   • For compatibility, we will start versioning at 100.
   • Tools that don't understand new instructions may reject the module outright or try to be flexible at parsing instructions that they may not understand.
2. Unified spec document: The specification document itself will be versioned internally.
   • New URL: The spec will live at a single, version-neutral URL: .../NonSemantic.Shader.DebugInfo.html
   • Internal versioning: The document will be updated to match the ClspvReflection spec:
     • A "Latest version" and "Date" section will be added to the top.
     • Changes will be documented inline (e.g., "...this operand is missing before version N.").

I would like to gather opinions on this proposal. Please share any thoughts, concerns, or requirements we should keep in mind as we formalize these changes.

@baldurk @danginsburg @s-perron @sajjadmirzanv @chaocNV for visibility. If you know of any others who may be affected by this, please tag them as well. Thanks.

[baldurk]

Seems straightforward and reasonable to me, changing the OpExtInstImport guarantees backwards compatibility for old modules but consumers can switch on any behaviours if they want to. You say you'd start the versioning at 100 - I assume that means there will be no changes to the spec at first and any changes would start with versions >100.

I don't have a strong opinion on the unified spec, it should probably be fine. My only thought is that potentially unlike other APIs there will be more motivation to change things in a non-backwards-compatible way and a unified spec may get messy if things are actively removed or particularly if instructions change, vs vulkan or SPIR-V that have stronger compatibility expectations.

[s-perron]

I don't see any problems with this general approach. However, there rough edges that could come up.

1. What will happen if two versions of the instruction set are requested?
2. Is there a guarantee that later versions will be strict supersets of previous versions?
3. Are there any guidelines on when a new version is appropriate vs totally new instruction set?

[alan-baker]

1. What will happen if two versions of the instruction set are requested?

This is reasonably straightforward since the extended instruction must refer to the imported set. So it is always clear what version is used. I'm not sure it's useful to do such a thing, so we could easily require that any debug instruction can only refer to other debug instructions from the same import as a validation rule.

2. Is there a guarantee that later versions will be strict supersets of previous versions?

I think yes. That can certainly be codified in the spec.

3. Are there any guidelines on when a new version is appropriate vs totally new instruction set?

A new set should never be required if this is done right. It might be advantageous to do so at some point in the distant future if we start accumulating too many variants of instructions (e.g. DebugDeclare, DebugDeclare2, DebugDeclare3, etc), but the goal would be to not require a new set as much as possible.

[sajjadmirzanv]

2. Is there a guarantee that later versions will be strict supersets of previous versions?

I think yes. That can certainly be codified in the spec.

Would that mean a later version can't have stricter validation rules? That's something I hoped we could get in a future version of the spec. There are a few cases where it allows some odd patterns that are painful to implement.

[s-perron]

There are a few cases where it allows some odd patterns that are painful to implement.

Implement where? For a compiler perspective, if the new spec provides a better way of representing the same debug information, you don't have to generate the old.

From a debugger perspective, they will have to support all versions anyway right? Or are you saying NSight will not support older versions of the debug info?

[dnovillo]

2. Is there a guarantee that later versions will be strict supersets of previous versions?

I think yes. That can certainly be codified in the spec.

Would that mean a later version can't have stricter validation rules? That's something I hoped we could get in a future version of the spec. There are a few cases where it allows some odd patterns that are painful to implement.

If I understand you correctly, validation will always validate at a given version level. So, if it's validating at NSDI.150, it should allow anything allowed in version 150. Any code patterns that are allowed to be generated at 150 should be validated successfully.

So, if a pattern was difficult to implement in version 120, but fixed in version 130, it should continue working at 150.

[dnovillo]

2. Is there a guarantee that later versions will be strict supersets of previous versions?

I think yes. That can certainly be codified in the spec.

Would that mean a later version can't have stricter validation rules? That's something I hoped we could get in a future version of the spec. There are a few cases where it allows some odd patterns that are painful to implement.

If I understand you correctly, validation will always validate at a given version level. So, if it's validating at NSDI.150, it should allow anything allowed in version 150. Any code patterns that are allowed to be generated at 150 should be validated successfully.

So, if a pattern was difficult to implement in version 120, but fixed in version 130, it should continue working at 150.

@sajjadmirzanv and I chatted about this concern offline. I was slightly misunderstanding Sajjad. The concern was about allowing old constructs to be deprecated in newer versions of the spec.

When we say that version N + 1 of the spec is a superset of version N, it does not mean that it's a compatible superset of it. For example, if version N supports a construct X with certain semantics that make it difficult to implement in compilers/tools, version N + 1 can modify the semantics of the construct without worrying about being backwards compatible with version N.

Tools that consume version N of debug info will continue to use the semantics in version N. It is up to the tool to drop backwards compatibility with version N of the spec. But the spec itself does not need to concern itself with that.

@sajjadmirzanv does that clarify?