[ViewVC] Diff of: cvs/cvsroot/libecb/ecb.pod

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.64 by root, Wed Feb 18 20:48:59 2015 UTC vs.
Revision 1.85 by root, Mon Jan 20 21:13:38 2020 UTC

 Its homepage can be found here:
     http://software.schmorp.de/pkg/libecb
-It mainly provides a number of wrappers around GCC built-ins, together
+It mainly provides a number of wrappers around many compiler built-ins,
-with replacement functions for other compilers. In addition to this,
+together with replacement functions for other compilers. In addition
-it provides a number of other lowlevel C utilities, such as endianness
+to this, it provides a number of other lowlevel C utilities, such as
-detection, byte swapping or bit rotations.
+endianness detection, byte swapping or bit rotations.
-Or in other words, things that should be built into any standard C system,
+Or in other words, things that should be built into any standard C
-but aren't, implemented as efficient as possible with GCC, and still
+system, but aren't, implemented as efficient as possible with GCC (clang,
-correct with other compilers.
+msvc...), and still correct with other compilers.
 More might come.
 =head2 ABOUT THE HEADER
 =head2 TYPES / TYPE SUPPORT
 ecb.h makes sure that the following types are defined (in the expected way):
-   int8_t   uint8_t   int16_t  uint16_t
+   int8_t       uint8_
-   int32_t  uint32_t  int64_t  uint64_t
+   int16_t      uint16_t
+   int32_t      uint32_
+   int64_t      uint64_t
+   int_fast8_t  uint_fast8_t
+   int_fast16_t uint_fast16_t
+   int_fast32_t uint_fast32_t
+   int_fast64_t uint_fast64_t
-   intptr_t uintptr_t
+   intptr_t     uintptr_t
 The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
 platform (currently C<4> or C<8>) and can be used in preprocessor
 expressions.
-For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
+For C<ptrdiff_t> and C<size_t> use C<stddef.h>/C<cstddef>.
 =head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
 All the following symbols expand to an expression that can be tested in
 preprocessor instructions as well as treated as a boolean (use C<!!> to
 =over 4
 =item ECB_C
 True if the implementation defines the C<__STDC__> macro to a true value,
-while not claiming to be C++.
+while not claiming to be C++, i..e C, but not C++.
 =item ECB_C99
 True if the implementation claims to be compliant to C99 (ISO/IEC
 9899:1999) or any later version, while not claiming to be C++.
 Note that later versions (ECB_C11) remove core features again (for
 example, variable length arrays).
-=item ECB_C11
+=item ECB_C11, ECB_C17
-True if the implementation claims to be compliant to C11 (ISO/IEC
+True if the implementation claims to be compliant to C11/C17 (ISO/IEC
-9899:2011) or any later version, while not claiming to be C++.
+9899:2011, :20187) or any later version, while not claiming to be C++.
 =item ECB_CPP
 True if the implementation defines the C<__cplusplus__> macro to a true
 value, which is typically true for C++ compilers.
-=item ECB_CPP11
+=item ECB_CPP11, ECB_CPP14, ECB_CPP17
-True if the implementation claims to be compliant to ISO/IEC 14882:2011
+True if the implementation claims to be compliant to C++11/C++14/C++17
-(C++11) or any later version.
+(ISO/IEC 14882:2011, :2014, :2017) or any later version.
+Note that many C++20 features will likely have their own feature test
+macros (see e.g. L<http://eel.is/c++draft/cpp.predefined#1.8>).
+=item ECB_OPTIMIZE_SIZE
+Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
+can also be defined before including F<ecb.h>, in which case it will be
+unchanged.
 =item ECB_GCC_VERSION (major, minor)
-Expands to a true value (suitable for testing in by the preprocessor)
+Expands to a true value (suitable for testing by the preprocessor) if the
-if the compiler used is GNU C and the version is the given version, or
+compiler used is GNU C and the version is the given version, or higher.
-higher.
 This macro tries to return false on compilers that claim to be GCC
 compatible but aren't.
 =item ECB_EXTERN_C
    ECB_EXTERN_C_END
 =item ECB_STDFP
-If this evaluates to a true value (suitable for testing in by the
+If this evaluates to a true value (suitable for testing by the
 preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
 and double/binary64 representations internally I<and> the endianness of
 both types match the endianness of C<uint32_t> and C<uint64_t>.
 This means you can just copy the bits of a C<float> (or C<double>) to an
 =over 4
 =item ecb_unused
 Marks a function or a variable as "unused", which simply suppresses a
-warning by GCC when it detects it as unused. This is useful when you e.g.
+warning by the compiler when it detects it as unused. This is useful when
-declare a variable but do not always use it:
+you e.g. declare a variable but do not always use it:
   {
     ecb_unused int var;
     #ifdef SOMECONDITION
 Similar to C<ecb_unused>, but marks a function, variable or type as
 deprecated. This makes some compilers warn when the type is used.
 =item ecb_deprecated_message (message)
-Same as C<ecb_deprecated>, but if possible, supply a diagnostic that is
+Same as C<ecb_deprecated>, but if possible, the specified diagnostic is
 used instead of a generic depreciation message when the object is being
 used.
 =item ecb_inline
-Expands either to C<static inline> or to just C<static>, if inline
+Expands either to (a compiler-specific equivalent of) C<static inline> or
-isn't supported. It should be used to declare functions that should be
+to just C<static>, if inline isn't supported. It should be used to declare
-inlined, for code size or speed reasons.
+functions that should be inlined, for code size or speed reasons.
 Example: inline this function, it surely will reduce codesize.
    ecb_inline int
    negmul (int a, int b)
      return - (a * b);
    }
 =item ecb_noinline
-Prevent a function from being inlined - it might be optimised away, but
+Prevents a function from being inlined - it might be optimised away, but
 not inlined into other functions. This is useful if you know your function
 is rarely called and large enough for inlining not to be helpful.
 =item ecb_noreturn
       real_reserve_method (size); /* presumably noinline */
   }
 =item ecb_assume (cond)
-Try to tell the compiler that some condition is true, even if it's not
+Tries to tell the compiler that some condition is true, even if it's not
-obvious.
+obvious. This is not a function, but a statement: it cannot be used in
+another expression.
 This can be used to teach the compiler about invariants or other
 conditions that might improve code generation, but which are impossible to
 deduce form the code itself.
 =item ecb_unreachable ()
 This function does nothing itself, except tell the compiler that it will
 never be executed. Apart from suppressing a warning in some cases, this
-function can be used to implement C<ecb_assume> or similar functions.
+function can be used to implement C<ecb_assume> or similar functionality.
 =item ecb_prefetch (addr, rw, locality)
 Tells the compiler to try to prefetch memory at the given C<addr>ess
 for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
 the data will likely be accessed very often, and values in between mean
 something... in between. The memory pointed to by the address does not
 need to be accessible (it could be a null pointer for example), but C<rw>
 and C<locality> must be compile-time constants.
+This is a statement, not a function: you cannot use it as part of an
+expression.
 An obvious way to use this is to prefetch some data far away, in a big
 array you loop over. This prefetches memory some 128 array elements later,
 in the hope that it will be ready when the CPU arrives at that location.
   int sum = 0;
 =item int ecb_ctz32 (uint32_t x)
 =item int ecb_ctz64 (uint64_t x)
+=item int ecb_ctz (T x) [C++]
 Returns the index of the least significant bit set in C<x> (or
 equivalently the number of bits set to 0 before the least significant bit
 set), starting from 0. If C<x> is 0 the result is undefined.
 For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
+The overloaded C++ C<ecb_ctz> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
 For example:
   ecb_ctz32 (3) = 0
   ecb_ctz32 (6) = 1
 =item bool ecb_is_pot32 (uint32_t x)
 =item bool ecb_is_pot64 (uint32_t x)
+=item bool ecb_is_pot (T x) [C++]
-Return true iff C<x> is a power of two or C<x == 0>.
+Returns true iff C<x> is a power of two or C<x == 0>.
-For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
+For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
+The overloaded C++ C<ecb_is_pot> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
 =item int ecb_ld32 (uint32_t x)
 =item int ecb_ld64 (uint64_t x)
+=item int ecb_ld64 (T x) [C++]
 Returns the index of the most significant bit set in C<x>, or the number
 of digits the number requires in binary (so that C<< 2**ld <= x <
 2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
 to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
 the given data type), while C<ecb_ld> returns how many bits the number
 itself requires.
 For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
+The overloaded C++ C<ecb_ld> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
 =item int ecb_popcount32 (uint32_t x)
 =item int ecb_popcount64 (uint64_t x)
+=item int ecb_popcount (T x) [C++]
 Returns the number of bits set to 1 in C<x>.
 For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
+The overloaded C++ C<ecb_popcount> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
 For example:
   ecb_popcount32 (7) = 3
   ecb_popcount32 (255) = 8
 =item uint16_t ecb_bitrev16 (uint16_t x)
 =item uint32_t ecb_bitrev32 (uint32_t x)
+=item T ecb_bitrev (T x) [C++]
 Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
 and so on.
+The overloaded C++ C<ecb_bitrev> function supports C<uint8_t>, C<uint16_t> and C<uint32_t> types.
 Example:
    ecb_bitrev8 (0xa7) = 0xea
    ecb_bitrev32 (0xffcc4411) = 0x882233ff
+=item T ecb_bitrev (T x) [C++]
+Overloaded C++ bitrev function.
+C<T> must be one of C<uint8_t>, C<uint16_t> or C<uint32_t>.
 =item uint32_t ecb_bswap16 (uint32_t x)
 =item uint32_t ecb_bswap32 (uint32_t x)
 =item uint64_t ecb_bswap64 (uint64_t x)
+=item T ecb_bswap (T x)
 These functions return the value of the 16-bit (32-bit, 64-bit) value
 C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
 C<ecb_bswap32>).
+The overloaded C++ C<ecb_bswap> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
 =item uint8_t  ecb_rotl8  (uint8_t  x, unsigned int count)
 =item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
 =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
 These two families of functions return the value of C<x> after rotating
 all the bits by C<count> positions to the right (C<ecb_rotr>) or left
 (C<ecb_rotl>).
-Current GCC versions understand these functions and usually compile them
+Current GCC/clang versions understand these functions and usually compile
-to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
+them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
-x86).
+on x86).
+=item T ecb_rotl (T x, unsigned int count) [C++]
+=item T ecb_rotr (T x, unsigned int count) [C++]
+Overloaded C++ rotl/rotr functions.
+C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
 =back
+=head2 HOST ENDIANNESS CONVERSION
+=over 4
+=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
+=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
+=item uint_fast64_t ecb_be_u64_to_host (uint_fast64_t v)
+=item uint_fast16_t ecb_le_u16_to_host (uint_fast16_t v)
+=item uint_fast32_t ecb_le_u32_to_host (uint_fast32_t v)
+=item uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
+Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order.
+The naming convention is C<ecb_>(C<be>|C<le>)C<_u>C<16|32|64>C<_to_host>,
+where C<be> and C<le> stand for big endian and little endian, respectively.
+=item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
+=item uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
+=item uint_fast64_t ecb_host_to_be_u64 (uint_fast64_t v)
+=item uint_fast16_t ecb_host_to_le_u16 (uint_fast16_t v)
+=item uint_fast32_t ecb_host_to_le_u32 (uint_fast32_t v)
+=item uint_fast64_t ecb_host_to_le_u64 (uint_fast64_t v)
+Like above, but converts I<from> host byte order to the specified
+endianness.
+=back
+In C++ the following additional template functions are supported:
+=over 4
+=item T ecb_be_to_host (T v)
+=item T ecb_le_to_host (T v)
+=item T ecb_host_to_be (T v)
+=item T ecb_host_to_le (T v)
+These functions work like their C counterparts, above, but use templates,
+which make them useful in generic code.
+C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
+(so unlike their C counterparts, there is a version for C<uint8_t>, which
+again can be useful in generic code).
+=head2 UNALIGNED LOAD/STORE
+These function load or store unaligned multi-byte values.
+=over 4
+=item uint_fast16_t ecb_peek_u16_u (const void *ptr)
+=item uint_fast32_t ecb_peek_u32_u (const void *ptr)
+=item uint_fast64_t ecb_peek_u64_u (const void *ptr)
+These functions load an unaligned, unsigned 16, 32 or 64 bit value from
+memory.
+=item uint_fast16_t ecb_peek_be_u16_u (const void *ptr)
+=item uint_fast32_t ecb_peek_be_u32_u (const void *ptr)
+=item uint_fast64_t ecb_peek_be_u64_u (const void *ptr)
+=item uint_fast16_t ecb_peek_le_u16_u (const void *ptr)
+=item uint_fast32_t ecb_peek_le_u32_u (const void *ptr)
+=item uint_fast64_t ecb_peek_le_u64_u (const void *ptr)
+Like above, but additionally convert from big endian (C<be>) or little
+endian (C<le>) byte order to host byte order while doing so.
+=item ecb_poke_u16_u (void *ptr, uint16_t v)
+=item ecb_poke_u32_u (void *ptr, uint32_t v)
+=item ecb_poke_u64_u (void *ptr, uint64_t v)
+These functions store an unaligned, unsigned 16, 32 or 64 bit value to
+memory.
+=item ecb_poke_be_u16_u (void *ptr, uint_fast16_t v)
+=item ecb_poke_be_u32_u (void *ptr, uint_fast32_t v)
+=item ecb_poke_be_u64_u (void *ptr, uint_fast64_t v)
+=item ecb_poke_le_u16_u (void *ptr, uint_fast16_t v)
+=item ecb_poke_le_u32_u (void *ptr, uint_fast32_t v)
+=item ecb_poke_le_u64_u (void *ptr, uint_fast64_t v)
+Like above, but additionally convert from host byte order to big endian
+(C<be>) or little endian (C<le>) byte order while doing so.
+=back
+In C++ the following additional template functions are supported:
+=over 4
+=item T ecb_peek<T>      (const void *ptr)
+=item T ecb_peek_be<T>   (const void *ptr)
+=item T ecb_peek_le<T>   (const void *ptr)
+=item T ecb_peek_u<T>    (const void *ptr)
+=item T ecb_peek_be_u<T> (const void *ptr)
+=item T ecb_peek_le_u<T> (const void *ptr)
+Similarly to their C counterparts, these functions load an unsigned 8, 16,
+32 or 64 bit value from memory, with optional conversion from big/little
+endian.
+Since the type cannot be deduced, it has to be specified explicitly, e.g.
+   uint_fast16_t v = ecb_peek<uint16_t> (ptr);
+C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
+Unlike their C counterparts, these functions support 8 bit quantities
+(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
+all of which hopefully makes them more useful in generic code.
+=item ecb_poke      (void *ptr, T v)
+=item ecb_poke_be   (void *ptr, T v)
+=item ecb_poke_le   (void *ptr, T v)
+=item ecb_poke_u    (void *ptr, T v)
+=item ecb_poke_be_u (void *ptr, T v)
+=item ecb_poke_le_u (void *ptr, T v)
+Again, similarly to their C counterparts, these functions store an
+unsigned 8, 16, 32 or z64 bit value to memory, with optional conversion to
+big/little endian.
+C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
+Unlike their C counterparts, these functions support 8 bit quantities
+(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
+all of which hopefully makes them more useful in generic code.
+=back
 =head2 FLOATING POINT FIDDLING
 =over 4
-=item ECB_INFINITY
+=item ECB_INFINITY [-UECB_NO_LIBM]
 Evaluates to positive infinity if supported by the platform, otherwise to
 a truly huge number.
-=item ECB_NAN
+=item ECB_NAN [-UECB_NO_LIBM]
 Evaluates to a quiet NAN if supported by the platform, otherwise to
 C<ECB_INFINITY>.
-=item float ecb_ldexpf (float x, int exp)
+=item float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
 Same as C<ldexpf>, but always available.
+=item uint32_t ecb_float_to_binary16  (float  x) [-UECB_NO_LIBM]
 =item uint32_t ecb_float_to_binary32  (float  x) [-UECB_NO_LIBM]
 =item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
 These functions each take an argument in the native C<float> or C<double>
-type and return the IEEE 754 bit representation of it.
+type and return the IEEE 754 bit representation of it (binary16/half,
+binary32/single or binary64/double precision).
 The bit representation is just as IEEE 754 defines it, i.e. the sign bit
 will be the most significant bit, followed by exponent and mantissa.
 This function should work even when the native floating point format isn't
 On all modern platforms (where C<ECB_STDFP> is true), the compiler should
 be able to optimise away this function completely.
 These functions can be helpful when serialising floats to the network - you
-can serialise the return value like a normal uint32_t/uint64_t.
+can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
 Another use for these functions is to manipulate floating point values
 directly.
 Silly example: toggle the sign bit of a float.
 =item float  ecb_binary16_to_float  (uint16_t x) [-UECB_NO_LIBM]
 =item float  ecb_binary32_to_float  (uint32_t x) [-UECB_NO_LIBM]
-=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM]
+=item double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
 The reverse operation of the previous function - takes the bit
-representation of an IEEE binary16, binary32 or binary64 number and
+representation of an IEEE binary16, binary32 or binary64 number (half,
-converts it to the native C<float> or C<double> format.
+single or double precision) and converts it to the native C<float> or
+C<double> format.
 This function should work even when the native floating point format isn't
 IEEE compliant, of course at a speed and code size penalty, and of course
 also within reasonable limits (it tries to convert normals and denormals,
 and might be lucky for infinities, and with extraordinary luck, also for
 negative zero).
 On all modern platforms (where C<ECB_STDFP> is true), the compiler should
 be able to optimise away this function completely.
+=item uint16_t ecb_binary32_to_binary16 (uint32_t x)
+=item uint32_t ecb_binary16_to_binary32 (uint16_t x)
+Convert a IEEE binary32/single precision to binary16/half format, and vice
+versa, handling all details (round-to-nearest-even, subnormals, infinity
+and NaNs) correctly.
+These are functions are available under C<-DECB_NO_LIBM>, since
+they do not rely on the platform floating point format. The
+C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
+usually what you want.
 =back
 =head2 ARITHMETIC
 C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
 negatable, that is, both C<m> and C<-m> must be representable in its
 type (this typically excludes the minimum signed integer value, the same
 limitation as for C</> and C<%> in C).
-Current GCC versions compile this into an efficient branchless sequence on
+Current GCC/clang versions compile this into an efficient branchless
-almost all CPUs.
+sequence on almost all CPUs.
 For example, when you want to rotate forward through the members of an
 array for increasing C<m> (which might be negative), then you should use
 C<ecb_mod>, as the C<%> operator might give either negative results, or
 change direction for negative values:
 dependencies on the math library (usually called F<-lm>) - these are
 marked with [-UECB_NO_LIBM].
 =back
+=head1 UNDOCUMENTED FUNCTIONALITY
+F<ecb.h> is full of undocumented functionality as well, some of which is
+intended to be internal-use only, some of which we forgot to document, and
+some of which we hide because we are not sure we will keep the interface
+stable.
+While you are welcome to rummage around and use whatever you find useful
+(we can't stop you), keep in mind that we will change undocumented
+functionality in incompatible ways without thinking twice, while we are
+considerably more conservative with documented things.
+=head1 AUTHORS
+C<libecb> is designed and maintained by:
+   Emanuele Giaquinta <e.giaquinta@glauco.it>
+   Marc Alexander Lehmann <schmorp@schmorp.de>

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing cvsroot/libecb/ecb.pod (file contents): Revision 1.64 by root, Wed Feb 18 20:48:59 2015 UTC vs. Revision 1.85 by root, Mon Jan 20 21:13:38 2020 UTC

Diff Legend

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.64 by root, Wed Feb 18 20:48:59 2015 UTC vs.
Revision 1.85 by root, Mon Jan 20 21:13:38 2020 UTC