--- cvsroot/libecb/ecb.pod 2011/06/01 01:29:36 1.27 +++ cvsroot/libecb/ecb.pod 2012/05/29 14:57:24 1.46 @@ -56,6 +56,66 @@ is usually implemented as a macro. Specifically, a "bool" in this manual refers to any kind of boolean value, not a specific type. +=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 + int32_t uint32_t int64_t uint64_t + intptr_t uintptr_t ptrdiff_t + +The macro C is defined to the size of a pointer on this +platform (currently C<4> or C<8>) and can be used in preprocessor +expressions. + +=head2 LANGUAGE/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 +ensure it's either C<0> or C<1> if you need that). + +=over 4 + +=item ECB_C + +True if the implementation defines the C<__STDC__> macro to a true value, +which is typically true for both C and C++ compilers. + +=item ECB_C99 + +True if the implementation claims to be C99 compliant. + +=item ECB_C11 + +True if the implementation claims to be C11 compliant. + +=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_CPP98 + +True if the implementation claims to be compliant to ISO/IEC 14882:1998 +(the first C++ ISO standard) or any later version. Typically true for all +C++ compilers. + +=item ECB_CPP11 + +True if the implementation claims to be compliant to ISO/IEC 14882:2011 +(C++11) or any later version. + +=item ECB_GCC_VERSION(major,minor) + +Expands to a true value (suitable for testing in by the preprocessor) +if the compiler used is GNU C and the version is the given version, or +higher. + +This macro tries to return false on compilers that claim to be GCC +compatible but aren't. + +=back + =head2 GCC ATTRIBUTES A major part of libecb deals with GCC attributes. These are additional @@ -103,6 +163,21 @@ #endif } +=item ecb_inline + +This is not actually an attribute, but you use it like one. It expands +either to C or to just C, if inline isn't +supported. It should be used to declare 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 @@ -383,7 +458,7 @@ =back -=head2 BIT FIDDLING / BITSTUFFS +=head2 BIT FIDDLING / BIT WIZARDRY =over 4 @@ -399,38 +474,104 @@ =item int ecb_ctz32 (uint32_t x) +=item int ecb_ctz64 (uint64_t x) + Returns the index of the least significant bit set in C (or equivalently the number of bits set to 0 before the least significant bit -set), starting from 0. If C is 0 the result is undefined. A common use -case is to compute the integer binary logarithm, i.e., C. For example: +set), starting from 0. If C is 0 the result is undefined. + +For smaller types than C you can safely use C. + +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) + +Return true iff C is a power of two or C. + +For smaller types then C you can safely use C. + +=item int ecb_ld32 (uint32_t x) + +=item int ecb_ld64 (uint64_t x) + +Returns the index of the most significant bit set in C, or the number +of digits the number requires in binary (so that C<< 2**ld <= x < +2**(ld+1) >>). If C is 0 the result is undefined. A common use case is +to compute the integer binary logarithm, i.e. C, for +example to see how many bits a certain number requires to be encoded. + +This function is similar to the "count leading zero bits" function, except +that that one returns how many zero bits are "in front" of the number (in +the given data type), while C returns how many bits the number +itself requires. + +For smaller types than C you can safely use C. + =item int ecb_popcount32 (uint32_t x) -Returns the number of bits set to 1 in C. For example: +=item int ecb_popcount64 (uint64_t x) + +Returns the number of bits set to 1 in C. + +For smaller types than C you can safely use C. + +For example: ecb_popcount32 (7) = 3 ecb_popcount32 (255) = 8 +=item uint8_t ecb_bitrev8 (uint8_t x) + +=item uint16_t ecb_bitrev16 (uint16_t x) + +=item uint32_t ecb_bitrev32 (uint32_t x) + +Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1 +and so on. + +Example: + + ecb_bitrev8 (0xa7) = 0xea + ecb_bitrev32 (0xffcc4411) = 0x882233ff + =item uint32_t ecb_bswap16 (uint32_t x) =item uint32_t ecb_bswap32 (uint32_t x) -These two functions return the value of the 16-bit (32-bit) value C -after reversing the order of bytes (0x11223344 becomes 0x44332211). +=item uint64_t ecb_bswap64 (uint64_t x) -=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count) +These functions return the value of the 16-bit (32-bit, 64-bit) value +C after reversing the order of bytes (0x11223344 becomes 0x44332211 in +C). + +=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 functions return the value of C after rotating all the bits -by C positions to the right or left respectively. +=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count) + +=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count) + +=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count) + +=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count) + +=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count) + +These two families of functions return the value of C after rotating +all the bits by C positions to the right (C) or left +(C). Current GCC versions understand these functions and usually compile them -to "optimal" code (e.g. a single C on x86). +to "optimal" code (e.g. a single C or a combination of C on +x86). =back @@ -450,11 +591,11 @@ C must be strictly positive (i.e. C<< >= 1 >>), while C must be negatable, that is, both C and C<-m> must be representable in its -type (this typically includes the minimum signed integer value, the same +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 -many systems. +almost all CPUs. For example, when you want to rotate forward through the members of an array for increasing C (which might be negative), then you should use @@ -464,6 +605,15 @@ for (m = -100; m <= 100; ++m) int elem = myarray [ecb_mod (m, ecb_array_length (myarray))]; +=item x = ecb_div_rd (val, div) + +=item x = ecb_div_ru (val, div) + +Returns C divided by C
rounded down or up, respectively. +C and C
must have integer types and C
must be strictly +positive. Note that these functions are implemented with macros in C +and with function templates in C++. + =back =head2 UTILITY @@ -482,4 +632,28 @@ =back +=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF + +These symbols need to be defined before including F the first time. + +=over 4 + +=item ECB_NO_THRADS + +If F is never used from multiple threads, then this symbol can +be defined, in which case memory fences (and similar constructs) are +completely removed, leading to more efficient code and fewer dependencies. + +Setting this symbol to a true value implies C. + +=item ECB_NO_SMP + +The weaker version of C - if F is used from +multiple threads, but never concurrently (e.g. if the system the program +runs on has only a single CPU with a single core, no hyperthreading and so +on), then this symbol can be defined, leading to more efficient code and +fewer dependencies. + +=back +