[RFC|oneMKL]Enable programmatic versioning

[vmalia]

Motivation

• Customers of oneMKL have requested a way to query the spec-compliance version of the implementation.
• The specification defines versioning but not in a programmatic way.
• Addresses Incomplete documentation about spec versioning #551

Inspiration

• SYCL versioning does not add the revision number:

---

• OpenMP specification itself keeps only MAJOR.MINOR version, with ongoing progress marked as Technical Report <number>. The _OPENMP macro provides a release date which maps onto a specification version, like this:

#define _OPENMP 202111    //202111: OpenMP 5.2

Proposal

• <MAJOR><MINOR><REVISION> such that MINOR and REVISION have two digits.
• Propose a macro for oneAPI and suggest a naming scheme for component macro names.

[rscohn2]

@uxlfoundation/oneapi-spec-maintainers: Please review this versioning proposal

[andrewtbarker]

I do not understand what is being proposed here.

Is the idea that each implementation of the spec gets to decide how to provide a version to the user (whether by a version string, a #define, an int getSpecVersion() function)? Then this change to the spec only specifies that the end of this string/macro/int has a certain representation?

[vmalia]

Is the idea that each implementation of the spec gets to decide how to provide a version to the user (whether by a version string, a #define, an int getSpecVersion() function)? Then this change to the spec only specifies that the end of this string/macro/int has a certain representation?

Yes. The goal of this RFC is to ensure that every implementation of the spec provides a numerically comparable value for its compliance with the spec version, through the proposed macros.

The implementation can additionally provide more ways to query that information, like APIs, but we do not mandate that in this proposal.

[vmalia]

@akukanov @mkrainiuk @rscohn2 @spencerpatty if everything looks okay, then please provide your approval. Thank you!

[spencerpatty]

Acceptable from my perspective. Approved

[vmalia]

@aelizaro @paveldyakov @lhuot @zettai-reido @sknepper can you please provide your reviews? Thank you!

[spencerpatty]

If/When we switch to oneMATH name for the Specification and Interfaces project, will we also switch the macro names ? maybe we want to delay this merge until those are made to not have to deprecate/switch ... ?

[vmalia]

@spencerpatty The changes you mentioned are from oneapi-src/oneMKL#564 which is an RFC in one of the implementations of this spec. The implementation can choose to take any direction, whether or not it is in compliance with the specification.

@Rbiessy you approved this PR earlier so there are 2 questions -

1. Does your RFC([RFC] oneMKL Interface renaming oneapi-src/oneMKL#564) block this RFC?
2. Does your RFC aim to make changes to the oneAPI specification eventually? If yes, can you please create a placeholder Issue/PR in this project and mention it here? If not, please note that your oneMKL Interfaces RFC breaks compliance with the oneAPI specification as of the current status of your RFC.

Note point number 5 in https://github.com/mkrainiuk/oneMKL/blob/rfcs/README.md#rfc-ratification-process

[vmalia]

I had an offline discussion with the team and we came to an agreement that the oneMATH proposal has a lot of work ahead of it, and that name change will have to be made in not just oneMKL Interfaces, but also in multiple places across oneAPI spec and other documents. Since this change will have a wider impact than just this specific part of document where this PR targets, it is better to make that change at that time. It will not affect the core version schema or approach proposed here.
This PR and RFC is NOT blocked by @Rbiessy 's RFC in oneMKL Interfaces.

[Rbiessy]

It does not matter to me which RFC is implemented first. The RFC for renaming is planning to rename the occurrences of all the macros using ONEMKL.
The RFC describes how it impacts the specification. I read the ratification process, it does not say that an issue needs to be created. @mkrainiuk could this be clarified in the RFC process? I created #580 but I have some concerns the discussions will be split in 2 different places now.

[mkrainiuk]

Hi @Rbiessy, good point, we need to clarify it in the ratification process, and I think any changes related to API should be discussed in Spec only, since opensource is just an implementation of the Spec, I believe it should just follow what was decided for Spec. In this particular case I guess the problem is that we have opensource project migration (which is not related to the Spec) combined with renaming (which is Spec related and should be started in the Spec).

[vmalia]

Thank you for clarifying, @mkrainiuk . @spencerpatty @Rbiessy Let's proceed with this RFC with the oneMKL naming. When the oneMATH proposal is made to the oneAPI spec, it can address these macros and other changes across the oneAPI spec simultaneously.

[al42and]

Do all headers provide this info? E.g.,

• Will #include "oneapi/mkl.hpp" provide ONEMKL_*_SPEC_VERSION for all domains?
  • If a domain is not supported/installed, will it be undefined or 0?
• Will #include "oneapi/mkl/rng.hpp" provide ONEMKL_RNG_SPEC_VERSION?
• Will #include "oneapi/mkl/rng.hpp" provide ONEMKL_BLAS_SPEC_VERSION?
• Will #include "oneapi/mkl/rng/device.hpp" provide ONEMKL_RNG_SPEC_VERSION?

[vmalia]

@al42and good question. The specification(and this RFC) does not define any implementation-specific header files for oneMKL, so the location of the macro can be decided by the implementation itself.

If a domain is not supported/installed, will it be undefined or 0?

For an undefined domain implementation, this, https://oneapi-src.github.io/oneMKL/create_new_backend.html#create-wrappers shows how the wrappers in oneMKL Interfaces work and how the implementation can handle errors for unimplemented backends. Note that this is different than the oneAPI specification that we have here. More clarification on that: https://github.com/oneapi-src/oneMKL/blob/develop/README.md#faqs

I added a rule for the macro numbering for the non-compliance of an implementation. Thanks!

[paveldyakov]

Question: Can domain be aligned with provisional spec version?
E.g. the latest available release is 1.4. provisional https://github.com/uxlfoundation/oneAPI-spec/releases

If yes, how we should update the macro in this case?

[vmalia]

@paveldyakov the provisional versioning (https://github.com/uxlfoundation/oneAPI-spec/blob/main/doc/versioning.rst#provisional-versions) is for specifications that are pending approval.

It is highly unlikely that we will have implementations that will comply with provisional specifications unless the approval of the spec happens later than the implementation in the backend library. If the backend is ready before the spec, the macro can point to a future non-provisional revision because the spec release follows a predictable convention.

From the above link:

A specification may be published before approval, but must be labeled provisional. Provisional specifications are published as a series of revisions until approval. After approval, the provisional label is removed and the rev is set to 1.

[sknepper]

Should we link to a document that describes how/when the MAJOR, MINOR, and revision versions get updated?

[vmalia]

Added at the end of this section.

[sknepper]

The oneMKL spec allows for an implementation of the spec to implement just 1 API and throw unsupported for all of the other APIs in that domain. (See https://github.com/uxlfoundation/oneAPI-spec/blob/main/source/elements/oneMKL/source/architecture/api_design.inc.rst)
In that case, is the implementation considered conformant to whatever version of the spec has the APIs that are included in the implementation (albeit mostly unsupported), or is that implementation considered non-compliant?

[vmalia]

My understanding is that the implementation will still be compliant, because it follows the definitions of the specification to handle errors for unimplemented APIs.

However, the implementation would not be conformant to the standards that the industry would expect "oneMKL" backend libraries to be, because of lack of most APIs.
Alternatively, it could be a feature that a specific hardware-software use case only requires or supports certain APIs as per their app's needs.