Any time that a macro in the crate references a primitive type it needs to say ::core::primitive::type instead of just type.

So any use of i32 should be ::core::primitive::i32 for example.

Obviously we want to support the Neon intrinsics for ARM.

• The current main blocker is that none of the Neon intrinsics are in Stable, and most of them aren't even in Nightly.

This will be basically like the 128-bit versions.

• Remember that the operator overload impl goes in the module that provides the function it uses, not in the module that defines the type it works on. In other words, the BitAnd impl for m128 goes into the sse module, not in the m128_ module.

It's not "ordinary" it's "ordered", as in "can be ordered" as in "not nan".

We should be more precise about how the mul_i64_widen_low_bits_m128i works, particularly is it just a strict i32 to i64 mul using the odd numbered lanes, or if you have the i64 lanes set with values outside the i32 range... what happens.

It's probably simple, but we should document it.

Change doctests to not use unsafe.

either with fancy iterators or something like that.

Also we probably won't do this all at once because it's a heck of a lot.

All of the crate's macros should be written like use ::core::arch::foo::bar; (leading ::) instead of just use core::arch::foo::bar;.

This should be a simple search and replace operation.

At first glance it seems like these can't be made safe and also totally zero-runtime-cost in an ergonomic way. I'm open to suggestions.

I hear these requested often enough when people talk about avx2, so I think if we can't do it safely with no runtime checks it would be permissible to expose versions of these that did some runtime checking if it was clearly marked as such.

• _mm_i32gather_epi32
• _mm_i32gather_epi64
• _mm_i32gather_pd
• _mm_i32gather_ps
• _mm_i64gather_epi32
• _mm_i64gather_epi64
• _mm_i64gather_pd
• _mm_i64gather_ps
• _mm_mask_i32gather_epi32
• _mm_mask_i32gather_epi64
• _mm_mask_i32gather_pd
• _mm_mask_i32gather_ps
• _mm_mask_i64gather_epi32
• _mm_mask_i64gather_epi64
• _mm_mask_i64gather_pd
• _mm_mask_i64gather_ps
• _mm256_i32gather_epi32
• _mm256_i32gather_epi64
• _mm256_i32gather_pd
• _mm256_i32gather_ps
• _mm256_i64gather_epi32
• _mm256_i64gather_epi64
• _mm256_i64gather_pd
• _mm256_i64gather_ps
• _mm256_mask_i32gather_epi32
• _mm256_mask_i32gather_epi64
• _mm256_mask_i32gather_pd
• _mm256_mask_i32gather_ps
• _mm256_mask_i64gather_epi32
• _mm256_mask_i64gather_epi64
• _mm256_mask_i64gather_pd
• _mm256_mask_i64gather_ps

We should inventory all the "convert" operations.

If necessary, we can come up with some sort of convention, or possibly more than one convention, and rename them for consistency.

The low-lane-only operations should be renamed to a better name. _low already kinda mixes with the unpack low and unpack high stuff.

_s was suggested for "scalar", which is as good a name as any.

I skipped them the first time around because they seem borderline useless anyway, but technically they should go in I guess.

It may be a good idea to replace super::* imports with imports to related types and core::arch::*

Any time that a macro in this crate uses a type from this crate, such as m128, we need to prefix that usage with $crate::. So for example it would become $crate::m128

There's a few problems with adding AVX-512 support:

• I don't have a device to develop on that even supports AVX-512 (for testing).
• Within Rust, it's all Nightly-only.

So (for now) we're blocked on adding avx512, but it'd be nice to have "some day".

This wouldn't be a 1.0 blocker, if we got to a state where we were otherwise 1.0 ready.

For any operation name that isn't already so common it's in the rust core lib (eg: add and sqrt) we should put them into the verb glossary.

And if it gets big enough, we might want to put the verb glossary on its own page.

Even if the user wants to enable features at compile time or not, it's helpful as an extra sanity check to be able to check at program start that the features really are available and maybe print an error message or something if the actual CPU isn't ready to handle what you're doing.

• first call __get_cpuid_max(0) and check ret.0 for the max leaf.
• If a leaf has sub-leaves you need to know the max of, call __get_cpuid_max(leaf) and check ret.1 for that max.
• once you know your limits, particular features can be checked for by getting the info for a leaf and checking the bits of a particular return register. Which bit you need to look for in what register in what leaf is mostly covered in the CPUID wikipedia article.

Right now you need the source files open to get intrinsic names, and then you'd also need to go to the intel intrinsics guide to see what the actual assembly instruction of the intrinsic is.

We can do better.

Proposed format:

/// short description.
///
/// extra details, if any
/// ```
/// doc test example
/// ```
/// * **Intrinsic:** [`name`]
/// * **Assembly:** `op arg, arg, arg`

Remember that the first line of the docs shows up in the function's summary when listing the functions of an entire module, so we want that to be short and sweet, and then everything past that first line can be various levels of info dump about what's going on.

Contribution Guidelines: If you want to try your hand at this, pick a small module with 10 or less functions (such as adx or bmi1) and do it for just that one small module. Then we can see if it's a comfortable format to look at and so on.

Currently all the tests are done via doc tests.

This means that most functions have only a single test case.

Particularly for a lot of the macros we probably want tests that check all sorts of edge cases. These should be put into the crate as integration tests (that is, modules in the tests/ folder).

• The blends can probably skip the word "immediate", in fact the probably all can. Or at least say "imm" or something?
• The shifts can probably use shl and shr

Difference between them:

• Shuffle is actually a = shuf(a, b, imm) (destructive)
• Permute is a = perm(b, imm) (immutable)

So permute has a lot less register pressure, and should be preferred when possible, if it's available.

This was noticed by @Soveu.

Thanks to the "two-layer paranoia" system this isn't actually a major bug, but we need to fix it obviously.

https://en.wikipedia.org/wiki/BLAKE_(hash_function)

A shuffled list of all the functions not from the "main line" of sse stuff up trough avx2.

Note that part of "the point" of doing it in this chaotic random order is to prevent you from accidentally making assumptions about one function based on the previous similar function. And also hopefully it will reduce the "boringness" of the task.

Also we probably won't do this all at once because it's a heck of a lot.

• unsigned __int64 _lzcnt_u64 (unsigned __int64 a)
• unsigned __int64 _andn_u64 (unsigned __int64 a, unsigned __int64 b)
• unsigned int _blsi_u32 (unsigned int a)
• __m128i _mm_aeskeygenassist_si128 (__m128i a, const int imm8)
• unsigned int _tzcnt_u32 (unsigned int a)
• int _rdrand64_step (unsigned __int64* val)
• unsigned __int64 _tzcnt_u64 (unsigned __int64 a)
• unsigned int _blsr_u32 (unsigned int a)
• int _rdseed32_step (unsigned int * val)
• unsigned int _pdep_u32 (unsigned int a, unsigned int mask)
• unsigned __int64 _mulx_u64 (unsigned __int64 a, unsigned __int64 b, unsigned __int64* hi)
• __m128i _mm_clmulepi64_si128 (__m128i a, __m128i b, const int imm8)
• __m128i _mm_aesdeclast_si128 (__m128i a, __m128i RoundKey)
• unsigned __int64 _pext_u64 (unsigned __int64 a, unsigned __int64 mask)
• unsigned __int64 _bextr2_u64 (unsigned __int64 a, unsigned __int64 control)
• int _rdseed16_step (unsigned short * val)
• unsigned int _andn_u32 (unsigned int a, unsigned int b)
• unsigned __int64 _blsmsk_u64 (unsigned __int64 a)
• unsigned int _blsmsk_u32 (unsigned int a)
• unsigned int _bextr2_u32 (unsigned int a, unsigned int control)
• int _rdrand16_step (unsigned short* val)
• unsigned char _addcarryx_u32 (unsigned char c_in, unsigned int a, unsigned int b, unsigned int * out)
• unsigned int _bextr_u32 (unsigned int a, unsigned int start, unsigned int len)
• unsigned __int64 _bzhi_u64 (unsigned __int64 a, unsigned int index)
• int _rdrand32_step (unsigned int* val)
• unsigned char _addcarryx_u64 (unsigned char c_in, unsigned __int64 a, unsigned __int64 b, unsigned __int64 * out)
• int _rdseed64_step (unsigned __int64 * val)
• unsigned __int64 _blsi_u64 (unsigned __int64 a)
• unsigned __int64 _pdep_u64 (unsigned __int64 a, unsigned __int64 mask)
• unsigned int _mulx_u32 (unsigned int a, unsigned int b, unsigned int* hi)
• __m128i _mm_aesenc_si128 (__m128i a, __m128i RoundKey)
• int _popcnt64 (__int64 a)
• int _popcnt32 (int a)
• unsigned int _lzcnt_u32 (unsigned int a)
• __m128i _mm_aesenclast_si128 (__m128i a, __m128i RoundKey)
• __m128i _mm_aesdec_si128 (__m128i a, __m128i RoundKey)
• unsigned int _bzhi_u32 (unsigned int a, unsigned int index)
• unsigned int _pext_u32 (unsigned int a, unsigned int mask)
• unsigned __int64 _blsr_u64 (unsigned __int64 a)
• __m128i _mm_aesimc_si128 (__m128i a)
• unsigned __int64 _bextr_u64 (unsigned __int64 a, unsigned int start, unsigned int len)

Not In Rust

• int _mm_tzcnt_32 (unsigned int a)
• __int64 _mm_tzcnt_64 (unsigned __int64 a)
• __int64 _mm_popcnt_u64 (unsigned __int64 a)
• int _mm_popcnt_u32 (unsigned int a)

The first time through I skipped over these because at first I didn't realize that they do have an inverse version that doesn't have undefined memory. I thought that the only inverses of these ops would just he undefined register content.

then i got to the end of the avx list and saw that you can zero-extend a register's high bits.

So now we want to have these in the lib again.

It'd be possible to do PartialEq for m128 by using cmp_eq and then moving the mask out and comparing with 0b1111.

But movemask is a costly thing and you shouldn't be branching on simd stuff as much as you should be merging values based on a mask and stuff.

So i dunno.

• avx uses set_splat
• sse2 uses just splat and drops the set. Others might also

probably we want to change everything to be set_splat and then we'd have "set" as one of our core verbs in the glossary and splat is just a modifier word.

It was suggested that we don't use a const, and instead make a zeroed register and compare it to itself to get the all 1s reg.

needs godbolt

This is the "1.0 goals list".

Before 1.0, everything on this list should either be added to the crate or examined and determined to be "post-1.0".

• If support for a feature is added to the crate (one module per feature), then we delete it from this list. There's too much stuff to keep everything in the list and just check off boxes.
• If a feature is examined and determined to be something we shouldn't support until post-1.0 (for some reason) then we'll break that off and make a separate issue for those items. In this case, those items would also be deleted from the list here.
• So once we're all done, the list will be empty.

This list was made with a little bit of regex being applied to the x86_64 list of what's stable in Rust 1.43.0 (2020-05-06).

. __cpuid
. __cpuid_count
. __get_cpuid_max

This is easy to do on a module-by-module basis, you just apply the attribute to each function in a module.

// example for "avx"
#[cfg_attr(docs_rs, doc(cfg(target_feature = "avx")))]

I just didn't start doing this at the beginning of crate development so someone has to go do this for previous work. With clever search and replace a person could probably update the entire crate in a matter of minutes.

document why a person would use negated comparisons.

It seems like the docs and even signature for _mm256_insertf128_si256 and _mm256_inserti128_si256 are essentially the same, however based on the names and the Felix Cloutier Notes it seems like _mm256_insertf128_si256 is mis-typed and should be operating on floating data, not integer data.

This would be a fairly simple fix, we can just throw in an extra cast or two if needed. The question is if this conclusion is correct and if we should make this adjustment for the user. Normally I'd be against safe_arch doing a "fix" like this but in this case it's the intel intrinsics who are wrapping the assembly wrong, so it feels fair to give proper direct access to the assembly.

Pings to:

• @joshtriplett
• @Evrey

Noticed that when using store_unaligned functions
I'll push changes with one additional test/bench

will break

this talks about "compliment" but should be "carry"

Compiler Explorer shows that there's some sort of difference between _mm_loadu_si128 and _mm_lddqu_si128, but I can't tell what and we need to investigate that probably.

We've got a number of getters and settters, and the names have become a little less consistent.

extract_i16_as_i32_m128i! should probably be "get" like the rest.

Also some of the "getters" don't get raw data they do a round, so that should be a "convert" maybe.

Naming is a mess.

--

Our naming rules are...

• "cast" preserves the exact bit patterns involved.
• ... ?

Any time a macro in this crate calls another branch of itself, we have to be sure to include the $crate:: prefix.

I think this is already handled, but it doesn't hurt to double check.

The docs for the struct types should be updated accordingly.

The "fused multiply add" operations. These don't all literally add, some of them subtract, but you get the idea.

there's like 193 ops here, or some crazy amount.

Update: It's a mess!

• _mm_permutevar_ps
• _mm256_permutevar_ps
• _mm_permutevar_pd
• _mm256_permutevar_pd
• _mm256_permutevar8x32_ps
• _mm256_permutevar8x32_epi32
• _mm_shuffle_epi8
• _mm256_shuffle_epi8
• _mm256_permute2f128_ps
• _mm256_permute2f128_pd
• _mm256_permute2f128_si256
• _mm256_permute2x128_si256
• _mm_shuffle_ps
• _mm256_shuffle_ps
• _mm_shuffle_pd
• _mm256_shuffle_pd
• _mm_permute_ps
• _mm_shuffle_epi32
• _mm256_permute_ps
• _mm_permute_pd
• _mm256_permute4x64_pd
• _mm256_permute_pd
• _mm_shufflehi_epi16
• _mm256_shufflehi_epi16
• _mm_shufflelo_epi16
• _mm256_shufflelo_epi16
• _mm256_shuffle_epi32
• _mm256_permute4x64_epi64

They are just annoying to type everytime

256-bit multiplies as well as all 512-bit ops draw more power and so clock down the core. Thus, we should potentially limit them behind a cargo feature so that you opt into them.

Also 512-bit multiplies are an additional level beyond that, so they can be separated again.

Since it doesn't hurt to do so, we might as well copy the name that the similar core::ops traits use for their method.