From 1c4709c6188527ba5dee40bcf868fbf9af0f17e0 Mon Sep 17 00:00:00 2001 From: "Duncan P. N. Exon Smith" Date: Mon, 23 Jun 2014 23:49:31 +0000 Subject: BFI: Update ScaledNumber header docs git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@211556 91177308-0d34-0410-b5e6-96231b3b80d8 --- include/llvm/Analysis/BlockFrequencyInfoImpl.h | 30 +++++++++++++++----------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'include') diff --git a/include/llvm/Analysis/BlockFrequencyInfoImpl.h b/include/llvm/Analysis/BlockFrequencyInfoImpl.h index ea1e958bb9..ffba30781f 100644 --- a/include/llvm/Analysis/BlockFrequencyInfoImpl.h +++ b/include/llvm/Analysis/BlockFrequencyInfoImpl.h @@ -68,25 +68,26 @@ public: } }; -/// \brief Simple representation of an unsigned floating point. +/// \brief Simple representation of a scaled number. /// -/// ScaledNumber is a unsigned floating point number. It uses simple -/// saturation arithmetic, and every operation is well-defined for every value. +/// ScaledNumber is a number represented by digits and a scale. It uses simple +/// saturation arithmetic and every operation is well-defined for every value. +/// It's somewhat similar in behaviour to a soft-float, but is *not* a +/// replacement for one. If you're doing numerics, look at \a APFloat instead. +/// Nevertheless, we've found these semantics useful for modelling certain cost +/// metrics. /// -/// The number is split into a signed exponent and unsigned digits. The number +/// The number is split into a signed scale and unsigned digits. The number /// represented is \c getDigits()*2^getExponent(). In this way, the digits are /// much like the mantissa in the x87 long double, but there is no canonical -/// form, so the same number can be represented by many bit representations -/// (it's always in "denormal" mode). +/// form so the same number can be represented by many bit representations. /// /// ScaledNumber is templated on the underlying integer type for digits, which -/// is expected to be one of uint64_t, uint32_t, uint16_t or uint8_t. -/// -/// Unlike builtin floating point types, ScaledNumber is portable. +/// is expected to be unsigned. /// /// Unlike APFloat, ScaledNumber does not model architecture floating point -/// behaviour (this should make it a little faster), and implements most -/// operators (this makes it usable). +/// behaviour -- while this might make it a little faster and easier to reason +/// about, it certainly makes it more dangerous for general numerics. /// /// ScaledNumber is totally ordered. However, there is no canonical form, so /// there are multiple representations of most scalars. E.g.: @@ -109,8 +110,11 @@ public: /// it trivial to add functionality to convert to APFloat (this is already /// relied on for the implementation of printing). /// -/// The current plan is to gut this and make the necessary parts of it (even -/// more) private to BlockFrequencyInfo. +/// Possible (and conflicting) future directions: +/// +/// 1. Turn this into a wrapper around \a APFloat. +/// 2. Share the algorithm implementations with \a APFloat. +/// 3. Allow \a ScaledNumber to represent a signed number. template class ScaledNumber : ScaledNumberBase { public: static_assert(!std::numeric_limits::is_signed, -- cgit v1.2.3