Add fmae which uses fmuladd

[GabrielMajeri]

Fixes #112.

When it comes to performance, the performance in my updated stencil benchmark with avx2 enabled is the same. But when avx2 is disabled, the avx fallback is much faster (before this pull request, I saw some 10x performance reduction on AVX 1).

So there are no downsides to this change, only performance improvements.

Also added some documentation for crate users.

I didn't rename the extern "C" fns, only changed the link_name attribute.

[gnzlbg]

So there are no downsides to this change,

So this isn't exactly accurate. The reason why, without this change the performance is worse, is IIUC because LLVM has to emulates the infinite precision of the fma instruction on the platforms that do not have it, which is expensive.

First, thank you for doing this, since I mainly test on an AVX1 machine and this is what I was seeing, and now we know that fmuladd is an intrinsic worth adding, since this is not something users can easily implement on their own, and it has a very big impact on the performance on some targets. I think we should do the following:

• keep ::fma as is, guaranteeing precision - add some tests (e.g. to the ./test directory) that check this (I don't know for which triple of values lower precision is observable, but maybe we can find something).

• add an fma-estimate method, e.g., ::fmae that uses fmuladd to produce an "estimate" of the infinite precision fma. On platforms that support it, it is exact, but on platforms that do not, it just does an a * b + c instead of trying to emulate the infinite precision.

• finally: update the aobench and other benchmarks to use ::fmae.

[GabrielMajeri]

@gnzlbg I've changed this PR as you said and implemented the fmae function. I haven't added the tests for the existing fma because I don't know which numbers to use when testing either.

[gnzlbg]

I think you need to put fma in ticks `` for the doc link to work properly.

[gnzlbg]

I haven't added the tests for the existing fma because I don't know which numbers to use when testing either.

I've been fuzzing fma and a * b + c for a while and I do not manage to get them to produce different results on my machine :/

[gnzlbg]

It seems that rustdoc trips on trying to generate the links - let's just remove the [ ] so that we can merge this. I've opened a PR to fix the clippy bot.

[GabrielMajeri]

@gnzlbg Alright, the links shouldn' be a problem since rustdoc will place these functions one next to another in the end.

I have removed the mention of fmsub from fma's documentation, because it didn't tell the full story anyway. x86 has additional intrinsics for advanced FMA stuff like fmaddsub, masked fma, etc.

LLVM will simply do its best to pick the right instruction, based on how fma is used.

Also, some bikeshedding: Rust's f32 primitive type has a mul_add function which (contrary to its name) will always use FMA (like the current fma function). Any reason for not choosing that name?

[gnzlbg]

Any reason for not choosing that name?

Oversight probably. Please open an issue about this. The floating-point methods are not in the initial round for stabilization so not much discussion has been going on about these.