1//===----------------------------------------------------------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8///
9/// \file
10/// Implementation of the exp2bf16 function, which computes 2^x for bfloat16.
11///
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_LIBC_SRC___SUPPORT_MATH_EXP2BF16_H
15#define LLVM_LIBC_SRC___SUPPORT_MATH_EXP2BF16_H
16
17#include "hdr/fenv_macros.h"
18#include "src/__support/FPUtil/FEnvImpl.h"
19#include "src/__support/FPUtil/FPBits.h"
20#include "src/__support/FPUtil/bfloat16.h"
21#include "src/__support/FPUtil/cast.h"
22#include "src/__support/FPUtil/except_value_utils.h"
23#include "src/__support/FPUtil/multiply_add.h"
24#include "src/__support/FPUtil/nearest_integer.h"
25#include "src/__support/FPUtil/polyeval.h"
26#include "src/__support/macros/attributes.h"
27#include "src/__support/macros/config.h"
28#include "src/__support/macros/optimization.h"
29
30namespace LIBC_NAMESPACE_DECL {
31namespace math {
32
33namespace exp2bf16_internal {
34// Generated by Sollya with the following commands:
35// > display = hexadecimal;
36// > for i in [|-126.5, -127, -127.5, -128, -129, -130, -131, -132, -133|]
37// do print(round(2^i, SG, RN) @ "f,");
38LIBC_INLINE_VAR constexpr float EXP2_DENORMAL[9] = {
39 0x1.6a09e8p-127f, 0x1p-127f, 0x1.6a09e8p-128f, 0x1p-128f, 0x1p-129f,
40 0x1p-130f, 0x1p-131f, 0x1p-132f, 0x1p-133f,
41};
42
43// Generated by Sollya with the following commands:
44// > display = hexadecimal;
45// > for i from 0 to 15 do print(round(2^(i/16), SG, RN) @ "f,");
46LIBC_INLINE_VAR constexpr float EXP2_MID[16] = {
47 0x1p0f, 0x1.0b5586p0f, 0x1.172b84p0f, 0x1.2387a6p0f,
48 0x1.306fep0f, 0x1.3dea64p0f, 0x1.4bfdaep0f, 0x1.5ab07ep0f,
49 0x1.6a09e6p0f, 0x1.7a1148p0f, 0x1.8ace54p0f, 0x1.9c4918p0f,
50 0x1.ae89fap0f, 0x1.c199bep0f, 0x1.d5818ep0f, 0x1.ea4afap0f,
51};
52} // namespace exp2bf16_internal
53
54LIBC_INLINE bfloat16 exp2bf16(bfloat16 x) {
55 using FPBits = fputil::FPBits<bfloat16>;
56 FPBits x_bits(x);
57 uint16_t x_uint = x_bits.uintval();
58
59 // We first check for NaN
60 if (LIBC_UNLIKELY(x_bits.is_nan())) {
61 // If it is a signaling NaN, then we raise an FE_INVALID exception
62 // and return a quiet NaN
63 if (x_bits.is_signaling_nan()) {
64 fputil::raise_except_if_required(FE_INVALID);
65 return FPBits::quiet_nan().get_val();
66 }
67 // If not, just return the NaN
68 return x;
69 }
70
71 // exp2bf16 may only give numeric output for input x in (-134.0, 128.0).
72 // All the remaining exceptional cases (overflow, underflow and denormal
73 // outputs) have |x| >= 126.5, so we filter them with a single check.
74 constexpr uint16_t EXCEPTIONAL_ABS_BASE = 0x42FD; // 0x1.fap6 = 126.5
75 if (LIBC_UNLIKELY(x_bits.abs().uintval() >= EXCEPTIONAL_ABS_BASE)) {
76 if (x_bits.is_pos()) {
77 // Overflow: x >= 128.0 (0x4300 = 0x1p7)
78 if (x_uint >= 0x4300) {
79 // exp2(Inf) = Inf
80 if (x_bits.is_inf())
81 return x;
82
83 return fputil::set_overflow<bfloat16>();
84 }
85 } else {
86 // Underflow: x <= -134.0 (0xC306 = -0x1.0cp7)
87 if (x_uint >= 0xC306) {
88 // exp2(-Inf) = 0
89 if (x_bits.is_inf())
90 return FPBits::zero().get_val();
91
92 return fputil::set_underflow<bfloat16>();
93 }
94
95 // Handle denormal output separately, by using a LUT
96 // We are handling these separately because the trick of adding hi
97 // directly to the exponent of the result will not work if the
98 // output is denormal. There are only 9 such inputs and they are
99 // all back-to-back when expressed as an uint16_t, with
100 // x_uint >= 0xC2FD (-0x1.fap6 = -126.5) and
101 // x_uint <= 0xC305 (-0x1.0ap7 = -133.0).
102 constexpr uint16_t DENORMAL_LUT_BASE = 0xC2FD;
103 return fputil::cast<bfloat16>(
104 x: exp2bf16_internal::EXP2_DENORMAL[x_uint - DENORMAL_LUT_BASE]);
105 }
106 }
107
108 // This interval rounds like 1 + x * log(2) in every bfloat16 mode.
109 // Double intermediates avoid underflow in the float polynomial for tiny x.
110 if (LIBC_UNLIKELY(x_bits.abs().uintval() <= 0x3980U)) {
111 double xd = static_cast<float>(x);
112 return fputil::cast<bfloat16>(
113 x: fputil::multiply_add(x: xd, y: 0x1.62e42fefa39efp-1, z: 1.0));
114 }
115
116 // For inputs not handled above in -134.0 < x < 128.0,
117 // we perform the following range reduction:
118 // x = hi + mid + lo
119 // where,
120 // hi is an integer
121 // mid is a grid point of the form j / 2^n in [0, 1)
122 // lo is what's leftover ie x - k / 2^n
123 // and |lo| <= 2^(-n-1)
124 // with,
125 // n = 4
126 // k = round(2^n * x)
127 // hi = k >> n
128 // j = k & (2^n - 1)
129 // then,
130 // exp2(x) = exp2(hi + mid + lo)
131 // = exp2(hi) * exp2(mid) * exp2(lo)
132 //
133 // To get exp2(hi), we'll just add hi to the exponent bits of the
134 // result of exp2(mid) * exp2(lo), which is exact.
135 // exp2(mid) we shall obtain by consulting our LUT,
136 // exp2(lo) by the polynomial.
137
138 float x_float = fputil::cast<float>(x);
139 float k_float = fputil::nearest_integer(x: x_float * 16.0f);
140
141 int k_int = static_cast<int>(k_float);
142 int hi = k_int >> 4;
143 int j = k_int & (16 - 1);
144
145 // lo = x - (hi + mid) = x - k / 2^n
146 // = k * (-2^(-n)) + x
147 float lo = fputil::sub_multiply(x: x_float, y: k_float, z: 0.0625f);
148
149 float exp2_mid = exp2bf16_internal::EXP2_MID[j];
150
151 // Degree-3 minimax polynomial generated by Sollya with the following
152 // commands:
153 // > display = hexadecimal;
154 // > P = fpminimax(2^x, [|1, 2, 3|], [|SG...|], [-2^-5, 2^-5], relative,
155 // floating, 1);
156 // 0x1p0 + x * (0x1.62e43p-1 + x * (0x1.ebfff4p-3 + x * 0x1.c6aceep-5))
157 float exp2_lo = fputil::polyeval(x: lo, a0: 0x1p0f, a: 0x1.62e43p-1f, a: 0x1.ebfff4p-3f,
158 a: 0x1.c6aceep-5f);
159
160 // We tried using Estrin's scheme as follows,
161 // float lo2 = lo * lo;
162 // float p0 = fputil::multiply_add(lo, 0x1.62e43p-1f, 0x1p0f);
163 // float p1 = fputil::multiply_add(lo, 0x1.c6aceep-5f, 0x1.ebfff4p-3f);
164 // float exp2_lo = fputil::multiply_add(lo2, p1, p0);
165 // however that led to a 1-ULP error in all RU, negative, small input cases.
166 // The latency increase wasn't significant (~1%) so we reverted back
167 // to Horner's scheme.
168
169 float res = exp2_mid * exp2_lo;
170
171 fputil::FPBits<float> res_bits(res);
172 uint32_t res_int = res_bits.uintval();
173
174 uint32_t exp_hi = hi << fputil::FPBits<float>::FRACTION_LEN;
175 res_int += exp_hi;
176
177 res = fputil::FPBits<float>(res_int).get_val();
178 return fputil::cast<bfloat16>(x: res);
179}
180
181} // namespace math
182} // namespace LIBC_NAMESPACE_DECL
183
184#endif // LLVM_LIBC_SRC___SUPPORT_MATH_EXP2BF16_H
185