Proposal for UR new warnings mechanism

[fabiomestre]

The warning mechanism that currently exists in Unified Runtime is ambiguous and not very intuitive.

This is the current state (for adapters that use this functionality):

• The entrypoint that wants to send a warning sets an error message for urAdapterGetLastError and returns UR_RESULT_ERROR_ADAPTER_SPECIFIC
• The call to urAdapterGetLastError returns UR_RESULT_SUCCESS to signal that it is a warning.
• If it is an actual error, The call to urAdapterGetLastErrorreturns UR_RESULT_ERROR_ADAPTER_SPECIFIC instead.

This is not intuitive because urAdapterGetLastError is the only entrypoint that can return an error code in a success state. In addition, setting UR_RESULT_SUCCESS to signal a warning doesn't make much sense.

After some internal discussion, we think that the following changes could improve the current workflow:

• Create a new loader entrypoint that accepts a callback function. This callback function will be called everytime a UR adapter emits a warning.
• The application would be able to opt out of warnings by simply not setting the callback function.
• At runtime, we can provide an environment variable to allow the user to enable/disable warnings.
• urAdapterGetLastError should be simplified to always return UR_RESULT_SUCCESS unless something is wrong with its parameters. This would make it behave in a way that is more in line with other UR entrypoints.

Risks:

• This would require some changes on the way that SYCL Runtime handles warnings and adapter specific errors from UR.

Related issue: https://github.com/oneapi-src/unified-runtime/issues/762

[fabiomestre]

This was discussed on the WG meeting of 14/02/2024. There was no objections to this approach. So we will go ahead with adding the new entrypoint to the specification.

[martygrant]

This has been implemented in https://github.com/intel/llvm/pull/17095