[Exp] Add Import/Release USM APIs using .yml.

[rdeodhar]

This change adds the definitions necessary for two new functions: USMImport and USMRelease.

USMImport converts host system memory into something akin to USM host memory.
USMRelease undoes the effect of a previous USMImport.

This functionality is used by SYCL to import/release host memory to speed up host <-> device data transfers.

[veselypeta]

Could you also include a EXP-USM-IMPORT-RELEASE.rst to document these experimental entry-points. You can refer to:

• https://github.com/oneapi-src/unified-runtime/pull/591/files#diff-9b138feff41c7ecdc35b6b7cebcab3c0eab0059fae9b43882960cd4edbf7cf29
• https://github.com/oneapi-src/unified-runtime/pull/594/files#diff-be2a36367d22ad851874b1c043be6db6e1c7e885dba42d182e5b87ac1be935ad

for examples on how to do this.

[kbenzie]

API changes look good, I echo @veselypeta's feedback about adding a .rst document describing the feature.

[rdeodhar]

I've added the file EXP-USM-IMPORT-RELEASE.rst as documentation.
How to use the $x notation was not clear to me. Please check.

[veselypeta]

LGTM. Just a suggestion on when you need to rebase your changes.

[veselypeta]

When you rebase - I recommend deleting these additions. After you rebase you can then rerun the generate script and it will assign you new values for these entry points. This is an unfortunate consequence of how the registry is generated.

[kbenzie]

In rst files use ${x}/${X} for the prefix:

Suggested change

	USMImport(hContext, hostPtr, size);
	${x}USMImport(hContext, hostPtr, size);

[rdeodhar]

If I prefix the function name with "${x}" then the generate step emits this error message:
Generating ../docs/source/core/EXP-USM-IMPORT-RELEASE.rst...
/iusers/rdeodhar/cmplr/ur_l0import/llvm/scripts/core/EXP-USM-IMPORT-RELEASE.rst(45) : error : symbol '$xUSMImport' not found
/iusers/rdeodhar/cmplr/ur_l0import/llvm/scripts/core/EXP-USM-IMPORT-RELEASE.rst(57) : error : symbol '$xUSMRelease' not found
Failed to generate specification.

That's why I had left it out. Perhaps x needs to be defined somewhere. Not clear to me how/where.

[rdeodhar]

Another question about the generated files:
Are some of them read-modify-write, or are they all simply generated, i.e. written?

[kbenzie]

That's why I had left it out. Perhaps x needs to be defined somewhere. Not clear to me how/where.

Okay, I'll have a look at this and see if the generator script is doing something different for this file compared to the others.

Are some of them read-modify-write, or are they all simply generated, i.e. written?

So anything in the include and source directories which the generator scripts touch are simply generated. scripts/core/registry.yml is different and it read/modify/write but only when a function is added/updated/removed.

[kbenzie]

That's why I had left it out. Perhaps x needs to be defined somewhere. Not clear to me how/where.

Okay, I'll have a look at this and see if the generator script is doing something different for this file compared to the others.

Are some of them read-modify-write, or are they all simply generated, i.e. written?

So anything in the include and source directories which the generator scripts touch are simply generated. scripts/core/registry.yml is different and it read/modify/write but only when a function is added/updated/removed.

The generator script validation was actually correct, these are missing the Exp suffix. I'll make suggestions on your new PR.

[kbenzie]

Suggested change

	USMRelease(hContext, hostPtr);
	${x}USMRelease(hContext, hostPtr);

[rdeodhar]

After doing a merge there were many conflicts.
Restarting in a new branch.
PR is #614

[kbenzie]

Restarting in a new branch.

If we can avoid this in future that would be very much appriciated. It makes reviewing and keeping track of changes much more difficult than it needs to be.

[kbenzie]

After doing a merge there were many conflicts.

We do provide guidance on resolving conflicts in the hint box of the forks and pullrequests section of the contribution guide which may have helped.

[rdeodhar]

Moving to a new PR was a desperate measure. Sorry about that. The number and nature of conflicts seemed unreasonable.