Docs: Update Math API page

[adeljo-amd]

The goal of this PR is to improve the usability of the Math API page, by providing information about each function's maximum ULP error when compared against the C++ standard library (if applicable). It also highlights specific math functions which are unsupported too.

[randyh62]

Looks good to me, except for the missing data related to the functions that don't run on GPUs.

[neon60]

@adeljo-amd Could you please rebase the branch?

[adeljo-amd]

@adeljo-amd Could you please rebase the branch?

Done

[adeljo-amd]

@neon60 Updated and added test ranges too

[g-h-c]

I find the explanation of ffs() might lack information. ffs() returns 0 if the integer has no bit set to 1. i.e.

• ffs(0) returns 0
• ffs(x) returns the position of the first bit set in x +1

Also should we warn that fns() calls are potentially slower? (as the compiler does not have a intrinsic for them, unlike ffs()):

• ffs() uses the ff1 instruction present both in RDNA and CDNA. See https://godbolt.org/z/3ncG3E99o
• fns() has no equivalent intrinsic, and it is implemented with a loop in the CLR.

[adeljo-amd]

I find the explanation of ffs() might lack information. ffs() returns 0 if the integer has no bit set to 1. i.e.

• ffs(0) returns 0
• ffs(x) returns the position of the first bit set in x +1

Also should we warn that fns() calls are potentially slower? (as the compiler does not have a intrinsic for them, unlike ffs()):

• ffs() uses the ff1 instruction present both in RDNA and CDNA. See https://godbolt.org/z/3ncG3E99o
• fns() has no equivalent intrinsic, and it is implemented with a loop in the CLR.

@g-h-c These are fair suggestions - it probably won't be necessary to mention that ffs() calls ff1, but it would be good to highlight that fns() is implemented via software rather than via hardware intrinsics.

Besides updating the ffs() description, I think it would be good to align this with ffsll(), which I imagine has the same behavior

[adeljo-amd]

@g-h-c Fixed, let me know what you think

[jujiang-del]

Looked through math APIs, please double check the following,
Supported functions, missing:
float fdividef(float x, float y)
Divide two floating point values.

float fmaf(float x, float y, float z)
Returns x⋅y+z as a single operation.

float fmaxf(float x, float y)
Determine the maximum numeric value of x and y.

float fminf(float x, float y)
Determine the minimum numeric value of x and y.

float fmodf(float x, float y)
Returns the floating-point remainder of x/y.

float hypotf(float x, float y)
Returns the square root of the sum of squares of x and y.

int ilogbf(float x)
Returns the unbiased integer exponent of x.

float tgammaf(float x)
Returns the gamma function of x.

double erfcinv(double x)
Returns the inverse complementary function of x.

double erfinv(double x)
Returns the inverse error function of x.

double j0(double x)
Returns the value of the Bessel function of the first kind of order 0 for x.

Unsupported on the device, missing.
float frexpf(float x, int* nptr)
Extract mantissa and exponent of x.

float modff(float x, float* iptr)
Break down x into fractional and integral parts.

float lgammaf(float x)
Returns the natural logarithm of the absolute value of the gamma function of x.

float nextafterf(float x, float y)
Returns next representable single-precision floating-point value after argument.

double remquo(double x, double y, int* quo)
Returns double-precision floating-point remainder and part of quotient.

[adeljo-amd]

Thanks @jujiang-del , I am indeed missing fdividef, but I'm not sure I follow the rest of the list, as they are already in there. Even the ones you listed as unsupported are in the page - and it would appear that they are supported on device as I was able to run them in kernels (it's how I got the ULP differences) on my local machine

[jujiang-del]

Thanks.