Document memory layout of vector types

[danderson]

Fixes #327

[Shnatsel]

Thanks! I like the tests. We might even enforce stronger layout guarantees later, since we do align 512-bit vectors to 512 bits on all platforms AFAIK. Doesn't have to happen as part of this PR though.

It would also be nice to document that the layout of masks varies between platforms and shouldn't be relied upon.

I don't recall if our vectors are repr(C) right now, we might want to make them if they aren't (and see if that alters the layout in any way).

[DJMcNab]

Welcome!

For awareness, our docs are intended to be built with all features enabled. If you look at https://docs.rs/fearless_simd/latest/fearless_simd/#feature-flags for example, you will see that this link is resolved.

In the past, we've fixed this with a conditional compilation approach:

https://docs.rs/color/latest/src/color/lib.rs.html#75

I'm not going to die on this hill though.
If you are going to apply this fix as-is, you need to remove the duplicate link in README.md (once you've regenned it)

[danderson]

Aah, I see. In that case, since it was a random unrelated change to this PR anyway, I'll just drop out that doc change. I'll send a followup that fixes this with a conditional, and does it properly with cargo-rdme. Thanks for the pointers!

[danderson]

I had a brain fart when I first wrote the PR, and got my bits and bytes confused. After looking again: yes, the vector types are all repr(C) already, and their alignment is forced up to their size (so, 512-bit alignment for 512-bit types, even on simd levels that implement them with 128-bit native types).

I've corrected the doc description, and changed the alignment tests to check that align_of >= size_of. If we're comfortable saying that no future supported SIMD ISA will have native types with higher-than-natural alignment (e.g. a 512-bit register type that requires 1024-bit alignment), we could make the alignment check == instead and remove "at least" from the documented promise.

I was going to change the docs of the mask types as well, but it turns out they already document that the layout is opaque and not guaranteed:

The storage representation of this type is intentionally opaque and may vary depending on the SIMD level.

[Shnatsel]

If we're comfortable saying that no future supported SIMD ISA will have native types with higher-than-natural alignment (e.g. a 512-bit register type that requires 1024-bit alignment), we could make the alignment check == instead and remove "at least" from the documented promise.

Alignment larger than the size would be wasteful: if the vectors laid out sequentially in memory, in an array, half the memory would just be wasted on padding. So I'm comfortable making a call that this is never going to happen. I've checked and no SIMD architecture or ABI does this today.

[danderson]

Sounds good. Updated the docs to say that the alignment is exactly size_of bytes, and updated the tests to reflect that.