Implement a high-level API and crate for ittapi

[bnjbvr]

This is a work-in-progress of what a high-level API and crate could look like for ittapi. This creates a small workspace in ittapi-rs with two sub-crates:

• ittapi-sys, which contains all the low-level bindings: it's the unmodified crate that's called ittapi-rs right now.
• ittapi, which contains higher-level bindings, and what ought to be sufficient for wasmtime.

It would need to be cleaned up a bit, and commented, with examples, etc. But wanted to post early progress, if people wanted to try it out and confirm it works for their use case.

[bnjbvr]

High-level usage example: https://github.com/bnjbvr/wasmtime/blob/high-level-vtune/crates/jit/src/profiling/vtune_linux.rs

[abrown]

cc: @jlb6740

[abrown]

Initial feedback:

• the crate split makes sense to me
• glancing around at the C documentation, I wonder if we should try to match the logical structure of the components there: e.g., jit::Method::load(...) -> Method, jit::notify_event(..., &Method), and over in the ITT part, itt::Domain::new(...) -> Domain, itt::task_begin(&Domain, ...), etc. I'm not saying we also can't have "do multiple things" helpers like here but it may help users to have an easy map from the C components to Rust structures--thoughts?

[bnjbvr]

Good idea! Did just that, and now the API resembles much the one from the C documentation, with naming that's closed to the one from the C documentation. This looks like a mid-level API now, but that seems fine; additional helpers can be built on top of this to make it really really easy to use.

[bnjbvr]

Quite satisfied with the current state of this crate now, calling it ready for review 🎉

[jlb6740]

@bnjbvr Hi .. so effectively this just hides the need to encapsulate calls with unsafe and other minor details to the api user, correct? Simplifies the ITTAPIs. How does someone who uses the abstraction know that a call is unsafe?

[abrown]

Had these comments pending and forgot to submit them.

[abrown]

I think the copy-c-library.ps1 script should also get an extra parent level due to this change.

[abrown]

Suggested change

	/// Notifies any `EventType` to Vtune.
	/// Notifies any `EventType` to VTune.

[bnjbvr]

Did a round of checking capitalization:

• in Rust it's a bit uncommon to have two capital letters following each other, so kept Vtune, but I don't care too much about it.
• used "VTune" in all comments though

[bnjbvr]

@bnjbvr Hi .. so effectively this just hides the need to encapsulate calls with unsafe and other minor details to the api user, correct? Simplifies the ITTAPIs. How does someone who uses the abstraction know that a call is unsafe?

The whole purpose of such a high-level crate is to hide all the unsafety. In general, the -sys crate exposes mostly unsafe functions, and the high-level one wraps those unsafe functions into safe functions, assuming that most/all the calls will effectively work. It's the idiomatic way of wrapping low-level bindings in the Rust community, as far as I know.