Runtime: Intrinsics are not documented

[MajorScruffy]

As someone who has never worked with intrinsics before, I wanted to have a look at the documentation to see what APIs are available, and what can actually be achieved with them. To my dismay, the documentation for all methods was basically just the declaration of the native function.

Let's take Avx2.Add(Vector256, Vector256) as an example. The documentation is just:

__m256i _mm256_add_epi64 (__m256i a, __m256i b)
VPADDQ ymm, ymm, ymm/m256

That doesn't tell me anything about what the method does. So if I want to see what it does, I have to copy "_mm256_add_epi64" and paste it on Intel's Intrinsics Guide.

As you can imagine, doing this for every method gets tiresome pretty fast. It would be much more helpful if the .NET documentation was the same as Intel's documentation.

[Dotnet-GitSync-Bot]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[Gnbrkm41]

My personal recommendation is https://www.felixcloutier.com/x86/index.html - it has all the instructions which you can search by name using Ctrl+F.

I'm personally worried about the amount of efforts this would require (there's thousands of intrinsics out there), and how much value it would hold (compared to, say, linking either the Intel intrinsics explorer page or the felixcloutier page). It would be a tremendous amount of effort and it has to be kept up-to-date in case something changes w.r.t the manual which isn't trivial.

[Gnbrkm41]

cc @tannergooding

[msftbot[bot]]

Tagging subscribers to this area: @tannergooding, @jeffhandley
See info in area-owners.md if you want to be subscribed.

[tannergooding]

CC. @terrajobst, has there been any update on being able to reuse the documentation from the architecture manuals?

[MajorScruffy]

@Gnbrkm41
How about using a source generator?
Just maintain a dictionary with .NET method -> Intrinsic name, and let the generator update the documentation whenever something changes.

[tannergooding]

@MajorScruffy, the issue isn't in writing some tool to port the documentation, it is in getting permission to reuse it.

The existing documentation are largely Copyright (c) Intel or Copyright (c) AMD and so we can't just freely take/use it in our own stuff without first getting permission.
The alternative is writing docs all ourselves, but that is a lot of effort and isn't readily doable without referring back to the original documentation, which then has a similar problem 😄.

[MajorScruffy]

@tannergooding
I don't know how difficult it would be to get permission from Intel or AMD, but it doesn't cost anything to ask.
The reason why I brought this up is because the quality of the documentation impacts adoption of any API. And adoption of the API influences how much effort is put in the future into improving/maintaining it.
I think Intrinsics are a great addition to .NET, and it would be nice to make them more accessible to those who are just getting started, especially since so much effort has already been put into writing the code. Besides, what we have today is a bit embarrassing when the rest of the .NET documentation is great 😄

The alternative is writing docs all ourselves, but that is a lot of effort and isn't readily doable without referring back to the original documentation, which then has a similar problem 😄.

Writing the documentation manually is clearly overkill, but perhaps links to Intel's documentation for every method would be a good start and I doubt Intel would complain about that.

[danmosemsft]

Is it fair to assume that most folks likely to use the intrinsics will be advanced enough to be comfortable referring to the hardware manuals? ie., the only info they need is the mapping to the underlying instructions?

[tannergooding]

The mapping to the underlying instruction and corresponding native intrinsic is what we have today.

Linking back to something like:

• https://software.intel.com/sites/landingpage/IntrinsicsGuide/
• https://software.intel.com/content/www/us/en/develop/articles/intel-sdm.html
• https://developer.amd.com/resources/developer-guides-manuals/

Might provide some additional benefit, but that might also require sign-off, stable URLs, or other considerations.
A conversation with the right people has already been started, I'm just not sure where that is today.

CC @terrajobst who should be able to give an update.

[gfoidl]

@danmosemsft I agree.

the only info they need is the mapping to the underlying instructions?

This is already here (xml-doc).

And for usage workflow it's quite common to have a look at intrinsics guide. So copy & paste from the xml-doc to the search field is acceptable.

[Gnbrkm41]

Perhaps we can add hyperlinks to the relevant page of the Intel's/AMD's intrinsic guide on each functions?

Also, one suggestion - perhaps we can provide an easier way to map C-style intrinsic functions (e.g. _mm256_and_pd) or instruction mnemonics (e.g. VANDPD) into .NET equivalents? The other way around is fairly trivial since you could just look it up on the API browser and locate the relevant documents page, but I don't see an easy way to do the other way around. (I suppose I could use search engines, but still)

[gfoidl]

an easy way to do the other way around

I use the GH-repo search for this.