[libc][math] Implement scalbn, scalbnf, scalbnl.

[renyichen]

Summary

Implement scalbn via fptuil::ldexp for FLT_RADIX==2 case.
"unimplemented" otherwise.

[renyichen]

include other commits.

[renyichen]

Add darwin as well.

[renyichen]

Add scalbn.

[renyichen]

Add newline at end of file.

[renyichen]

• small fix

[renyichen]

Add scalbn, scalbnf, scalbnl.

[renyichen]

scalbn is supposed to compute more efficiently than directly performing x*FLT_RADIX^n as described in C99 Standard (in existing implementations, it doesn't necessary holds).
A rough compare has been performed locally by fixing n and test over the range defined in the existing infra for scalbnf(x, n):

	llvmlibc	glibc	directly calc x*exp2f(n)
n = 10 denormal range
avg runtime (ns/op)	13.7849	57.5703	58.7697
n = 10 normal range
avg runtime (ns/op)	9.71103	10.7406	13.6085

llvmlibc outperforms both glibc and directly calc.

Current optimization mechanisms in fputil::ldexp(): 1. early return if n is outside [-MAX_EXPONENT-MantissaWidth-1, MAX_EXPONENT+MantissaWidth+1]. 2. bit manipulation.

[sivachandra]

Thanks for the patch. Please wait for @lntue also to approve this.

[lntue]

libc/src/__support/FPUtil/ManipulationFunctions.h

119–122

These are exceptional cases, adding unlikely to these 2 conditions could potentially speed up the main cases.

[lntue]

Can you also update the status table in math.rst?

[renyichen]

Implement scalbn.

libc/config/darwin/arm/entrypoints.txt

set(TARGET_LIBM_ENTRYPOINTS
     libc.src.math.remquo
     libc.src.math.remquol
     libc.src.math.rint
     libc.src.math.rintf
     libc.src.math.rintl
     libc.src.math.round
     libc.src.math.roundf
     libc.src.math.roundl
+    libc.src.math.scalbn
+    libc.src.math.scalbnf
+    libc.src.math.scalbnl
     libc.src.math.sincosf
     libc.src.math.sinhf
     libc.src.math.sinf
     libc.src.math.sqrt
     libc.src.math.sqrtf
     libc.src.math.sqrtl
     libc.src.math.tanf
     libc.src.math.tanhf

libc/config/linux/aarch64/entrypoints.txt

set(TARGET_LIBM_ENTRYPOINTS
     libc.src.math.remquo
     libc.src.math.remquol
     libc.src.math.rint
     libc.src.math.rintf
     libc.src.math.rintl
     libc.src.math.round
     libc.src.math.roundf
     libc.src.math.roundl
+    libc.src.math.scalbn
+    libc.src.math.scalbnf
+    libc.src.math.scalbnl
     libc.src.math.sincosf
     libc.src.math.sinhf
     libc.src.math.sinf
     libc.src.math.sqrt
     libc.src.math.sqrtf
     libc.src.math.sqrtl
     libc.src.math.tanf
     libc.src.math.tanhf

libc/config/linux/x86_64/entrypoints.txt

set(TARGET_LIBM_ENTRYPOINTS
     libc.src.math.remquo
     libc.src.math.remquol
     libc.src.math.rint
     libc.src.math.rintf
     libc.src.math.rintl
     libc.src.math.round
     libc.src.math.roundf
     libc.src.math.roundl
+    libc.src.math.scalbn
+    libc.src.math.scalbnf
+    libc.src.math.scalbnl
     libc.src.math.sin
     libc.src.math.sincosf
     libc.src.math.sinhf
     libc.src.math.sinf
     libc.src.math.sqrt
     libc.src.math.sqrtf
     libc.src.math.sqrtl
     libc.src.math.tan

libc/config/windows/entrypoints.txt

set(TARGET_LIBM_ENTRYPOINTS
     libc.src.math.remquo
     libc.src.math.remquol
     libc.src.math.rint
     libc.src.math.rintf
     libc.src.math.rintl
     libc.src.math.round
     libc.src.math.roundf
     libc.src.math.roundl
+    libc.src.math.scalbn
+    libc.src.math.scalbnf
+    libc.src.math.scalbnl
     libc.src.math.sin
     libc.src.math.sincosf
     libc.src.math.sinf
     libc.src.math.sinhf
     libc.src.math.sqrt
     libc.src.math.sqrtf
     libc.src.math.sqrtl
     libc.src.math.tan

libc/docs/math.rst

 nan
 nearbyint      :green:`XA`      :green:`XA`     :green:`XA`
 nextafter      :green:`XA`      :green:`XA`     :green:`XA`
 nexttoward
 remainder      :green:`XA`      :green:`XA`     :green:`XA`
 remquo         :green:`XA`      :green:`XA`     :green:`XA`
 rint           :green:`XA`      :green:`XA`     :green:`XA`
 round          :green:`XA`      :green:`XA`     :green:`XA`
-scalbn
+scalbn         :green:`XA`      :green:`XA`     :green:`XA`
 signbit
 trunc          :green:`XA`      :green:`XA`     :green:`XA`
 ============== ================ =============== ======================
 
 Higher Math Functions
 ---------------------
 
 ============== ================ =============== ======================

libc/spec/stdc.td

HeaderSpec Math = HeaderSpec<
           FunctionSpec<"acosf", RetValSpec<FloatType>, [ArgSpec<FloatType>]>,
           FunctionSpec<"asinf", RetValSpec<FloatType>, [ArgSpec<FloatType>]>,
           FunctionSpec<"asin", RetValSpec<DoubleType>, [ArgSpec<DoubleType>]>,
           FunctionSpec<"atanf", RetValSpec<FloatType>, [ArgSpec<FloatType>]>,
 
           FunctionSpec<"acoshf", RetValSpec<FloatType>, [ArgSpec<FloatType>]>,
           FunctionSpec<"asinhf", RetValSpec<FloatType>, [ArgSpec<FloatType>]>,
           FunctionSpec<"atanhf", RetValSpec<FloatType>, [ArgSpec<FloatType>]>,
+
+          FunctionSpec<"scalbn", RetValSpec<DoubleType>, [ArgSpec<DoubleType>, ArgSpec<IntType>]>,
+          FunctionSpec<"scalbnf", RetValSpec<FloatType>, [ArgSpec<FloatType>, ArgSpec<IntType>]>,
+          FunctionSpec<"scalbnl", RetValSpec<LongDoubleType>, [ArgSpec<LongDoubleType>, ArgSpec<IntType>]>,
       ]
   >;
 
   HeaderSpec StdIO = HeaderSpec<
       "stdio.h",
       [
           Macro<"stdin">,
           Macro<"stderr">,

libc/src/__support/FPUtil/ManipulationFunctions.h

LIBC_INLINE T logb(T x) {
   }
 
   NormalFloat<T> normal(bits);
   return normal.exponent;
 }
 
 template <typename T, cpp::enable_if_t<cpp::is_floating_point_v<T>, int> = 0>
 LIBC_INLINE T ldexp(T x, int exp) {
+  if (unlikely(exp == 0))
+    return x;
   FPBits<T> bits(x);
-  if (bits.is_zero() || bits.is_inf_or_nan() || exp == 0)
+  if (unlikely(bits.is_zero() || bits.is_inf_or_nan()))
     return x;
 
   // NormalFloat uses int32_t to store the true exponent value. We should ensure
   // that adding |exp| to it does not lead to integer rollover. But, if |exp|
   // value is larger the exponent range for type T, then we can return infinity
   // early. Because the result of the ldexp operation can be a subnormal number,
   // we need to accommodate the (mantissaWidht + 1) worth of shift in
   // calculating the limit.

libc/src/math/CMakeLists.txt

 add_math_entrypoint_object(rint)
 add_math_entrypoint_object(rintf)
 add_math_entrypoint_object(rintl)
 
 add_math_entrypoint_object(round)
 add_math_entrypoint_object(roundf)
 add_math_entrypoint_object(roundl)
 
+add_math_entrypoint_object(scalbn)
+add_math_entrypoint_object(scalbnf)
+add_math_entrypoint_object(scalbnl)
+
 add_math_entrypoint_object(sincosf)
 
 add_math_entrypoint_object(sin)
 add_math_entrypoint_object(sinf)
 add_math_entrypoint_object(sinhf)
 
 add_math_entrypoint_object(sqrt)
 add_math_entrypoint_object(sqrtf)

libc/src/math/generic/CMakeLists.txt

add_entrypoint_object(
   HDRS
     ../pow.h
   DEPENDS
     .expf
     .logf
   COMPILE_OPTIONS
     -O3
 )
+
+add_entrypoint_object(
+  scalbn
+  SRCS
+    scalbn.cpp
+  HDRS
+    ../scalbn.h
+  DEPENDS
+    libc.src.__support.FPUtil.manipulation_functions
+  COMPILE_OPTIONS
+    -O3
+)
+
+add_entrypoint_object(
+  scalbnf
+  SRCS
+    scalbnf.cpp
+  HDRS
+    ../scalbnf.h
+  DEPENDS
+    libc.src.__support.FPUtil.manipulation_functions
+  COMPILE_OPTIONS
+    -O3
+)
+
+add_entrypoint_object(
+  scalbnl
+  SRCS
+    scalbnl.cpp
+  HDRS
+    ../scalbnl.h
+  DEPENDS
+    libc.src.__support.FPUtil.manipulation_functions
+  COMPILE_OPTIONS
+    -O3
+)

libc/src/math/generic/scalbn.cpp

+//===-- Single-precision scalbn function ----------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/math/scalbn.h"
+#include "src/__support/FPUtil/ManipulationFunctions.h"
+#include "src/__support/common.h"
+
+namespace __llvm_libc {
+
+LLVM_LIBC_FUNCTION(double, scalbn, (double x, int n)) {
+#if !defined(__FLT_RADIX__)
+#error __FLT_RADIX__ undefined.
+#elif __FLT_RADIX__ != 2
+#error __FLT_RADIX__!=2, unimplemented.
+#else
+  return fputil::ldexp(x, n);
+#endif
+}
+
+} // namespace __llvm_libc

libc/src/math/generic/scalbnf.cpp

+//===-- Single-precision scalbnf function ---------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/math/scalbnf.h"
+#include "src/__support/FPUtil/ManipulationFunctions.h"
+#include "src/__support/common.h"
+
+namespace __llvm_libc {
+
+LLVM_LIBC_FUNCTION(float, scalbnf, (float x, int n)) {
+#if !defined(__FLT_RADIX__)
+#error __FLT_RADIX__ undefined.
+#elif __FLT_RADIX__ != 2
+#error __FLT_RADIX__!=2, unimplemented.
+#else
+  return fputil::ldexp(x, n);
+#endif
+}
+
+} // namespace __llvm_libc

libc/src/math/generic/scalbnl.cpp

+//===-- Single-precision scalbnl function ---------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/math/scalbnl.h"
+#include "src/__support/FPUtil/ManipulationFunctions.h"
+#include "src/__support/common.h"
+
+namespace __llvm_libc {
+
+LLVM_LIBC_FUNCTION(long double, scalbnl, (long double x, int n)) {
+#if !defined(__FLT_RADIX__)
+#error __FLT_RADIX__ undefined.
+#elif __FLT_RADIX__ != 2
+#error __FLT_RADIX__!=2, unimplemented.
+#else
+  return fputil::ldexp(x, n);
+#endif
+}
+
+} // namespace __llvm_libc

libc/src/math/scalbn.h

+//===-- Implementation header for scalbn ------------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_MATH_SCALBN_H
+#define LLVM_LIBC_SRC_MATH_SCALBN_H
+
+namespace __llvm_libc {
+
+double scalbn(double x, int n);
+
+} // namespace __llvm_libc
+
+#endif // LLVM_LIBC_SRC_MATH_SCALBN_H

libc/src/math/scalbnf.h

+//===-- Implementation header for scalbnf -----------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_MATH_SCALBNF_H
+#define LLVM_LIBC_SRC_MATH_SCALBNF_H
+
+namespace __llvm_libc {
+
+float scalbnf(float x, int n);
+
+} // namespace __llvm_libc
+
+#endif // LLVM_LIBC_SRC_MATH_SCALBNF_H

libc/src/math/scalbnl.h

+//===-- Implementation header for scalbnl -----------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_MATH_SCALBNL_H
+#define LLVM_LIBC_SRC_MATH_SCALBNL_H
+
+namespace __llvm_libc {
+
+long double scalbnl(long double x, int n);
+
+} // namespace __llvm_libc
+
+#endif // LLVM_LIBC_SRC_MATH_SCALBNL_H

libc/test/src/math/CMakeLists.txt

 add_fp_unittest(
   pow_test
   NEED_MPFR
   SUITE
     libc_math_unittests
   SRCS
     pow_test.cpp
   DEPENDS
     libc.include.errno
     libc.src.errno.errno
     libc.src.math.pow
 )
 
+add_fp_unittest(
+  scalbn_test
+  NEED_MPFR
+  SUITE
+    libc_math_unittests
+  SRCS
+    scalbn_test.cpp
+  HDRS
+    ScalbnTest.h
+  DEPENDS
+    libc.include.math
+    libc.src.math.scalbn
+    libc.src.__support.FPUtil.fp_bits
+    libc.src.__support.FPUtil.normal_float
+)
+
+add_fp_unittest(
+  scalbnf_test
+  NEED_MPFR
+  SUITE
+    libc_math_unittests
+  SRCS
+    scalbnf_test.cpp
+  HDRS
+    ScalbnTest.h
+  DEPENDS
+    libc.include.math
+    libc.src.math.scalbnf
+    libc.src.__support.FPUtil.fp_bits
+    libc.src.__support.FPUtil.normal_float
+)
+
+add_fp_unittest(
+  scalbnl_test
+  NEED_MPFR
+  SUITE
+    libc_math_unittests
+  SRCS
+    scalbnl_test.cpp
+  HDRS
+    ScalbnTest.h
+  DEPENDS
+    libc.include.math
+    libc.src.math.scalbnl
+    libc.src.__support.FPUtil.fp_bits
+    libc.src.__support.FPUtil.normal_float
+)
+
 add_subdirectory(generic)
 add_subdirectory(exhaustive)
 add_subdirectory(differential_testing)

libc/test/src/math/ScalbnTest.h

+//===-- Utility class to test different flavors of scalbn -------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_TEST_SRC_MATH_SCALBN_H
+#define LLVM_LIBC_TEST_SRC_MATH_SCALBN_H
+
+#include "LdExpTest.h"
+#include "utils/UnitTest/Test.h"
+
+#define LIST_SCALBN_TESTS(T, func)                                             \
+  using LlvmLibcScalbnTest = LdExpTestTemplate<T>;                             \
+  TEST_F(LlvmLibcScalbnTest, SpecialNumbers) { testSpecialNumbers(&func); }    \
+  TEST_F(LlvmLibcScalbnTest, PowersOfTwo) { testPowersOfTwo(&func); }          \
+  TEST_F(LlvmLibcScalbnTest, OverFlow) { testOverflow(&func); }                \
+  TEST_F(LlvmLibcScalbnTest, UnderflowToZeroOnNormal) {                        \
+    testUnderflowToZeroOnNormal(&func);                                        \
+  }                                                                            \
+  TEST_F(LlvmLibcScalbnTest, UnderflowToZeroOnSubnormal) {                     \
+    testUnderflowToZeroOnSubnormal(&func);                                     \
+  }                                                                            \
+  TEST_F(LlvmLibcScalbnTest, NormalOperation) { testNormalOperation(&func); }
+
+#endif // LLVM_LIBC_TEST_SRC_MATH_SCALBN_H

libc/test/src/math/scalbn_test.cpp

+//===-- Unittests for scalbn ----------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "ScalbnTest.h"
+
+#include "src/math/scalbn.h"
+
+LIST_SCALBN_TESTS(double, __llvm_libc::scalbn)

libc/test/src/math/scalbnf_test.cpp

+//===-- Unittests for scalbnf ---------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "ScalbnTest.h"
+
+#include "src/math/scalbnf.h"
+
+LIST_SCALBN_TESTS(float, __llvm_libc::scalbnf)

libc/test/src/math/scalbnl_test.cpp

+//===-- Unittests for scalbnl ---------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "ScalbnTest.h"
+
+#include "src/math/scalbnl.h"
+
+LIST_SCALBN_TESTS(long double, __llvm_libc::scalbnl)