ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
(Generate patch)

Comparing libecb/ecb.pod (file contents):
Revision 1.38 by sf-exg, Thu Aug 25 16:06:08 2011 UTC vs.
Revision 1.53 by root, Wed Dec 5 16:31:27 2012 UTC

… …
53C<uint32_t>, then the corresponding function works only with that type. If 53C<uint32_t>, then the corresponding function works only with that type. If
54only a generic name is used (C<expr>, C<cond>, C<value> and so on), then 54only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
55the corresponding function relies on C to implement the correct types, and 55the corresponding function relies on C to implement the correct types, and
56is usually implemented as a macro. Specifically, a "bool" in this manual 56is usually implemented as a macro. Specifically, a "bool" in this manual
57refers to any kind of boolean value, not a specific type. 57refers to any kind of boolean value, not a specific type.
58
59=head2 TYPES / TYPE SUPPORT
60
61ecb.h makes sure that the following types are defined (in the expected way):
62
63 int8_t uint8_t int16_t uint16_t
64 int32_t uint32_t int64_t uint64_t
65 intptr_t uintptr_t
66
67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
68platform (currently C<4> or C<8>) and can be used in preprocessor
69expressions.
70
71For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
72
73=head2 LANGUAGE/COMPILER VERSIONS
74
75All the following symbols expand to an expression that can be tested in
76preprocessor instructions as well as treated as a boolean (use C<!!> to
77ensure it's either C<0> or C<1> if you need that).
78
79=over 4
80
81=item ECB_C
82
83True if the implementation defines the C<__STDC__> macro to a true value,
84which is typically true for both C and C++ compilers.
85
86=item ECB_C99
87
88True if the implementation claims to be compliant to C99 (ISO/IEC
899899:1999) or any later version.
90
91Note that later versions (ECB_C11) remove core features again (for
92example, variable length arrays).
93
94=item ECB_C11
95
96True if the implementation claims to be compliant to C11 (ISO/IEC
979899:2011) or any later version.
98
99=item ECB_CPP
100
101True if the implementation defines the C<__cplusplus__> macro to a true
102value, which is typically true for C++ compilers.
103
104=item ECB_CPP11
105
106True if the implementation claims to be compliant to ISO/IEC 14882:2011
107(C++11) or any later version.
108
109=item ECB_GCC_VERSION(major,minor)
110
111Expands to a true value (suitable for testing in by the preprocessor)
112if the compiler used is GNU C and the version is the given version, or
113higher.
114
115This macro tries to return false on compilers that claim to be GCC
116compatible but aren't.
117
118=item ECB_EXTERN_C
119
120Expands to C<extern "C"> in C++, and a simple C<extern> in C.
121
122This can be used to declare a single external C function:
123
124 ECB_EXTERN_C int printf (const char *format, ...);
125
126=item ECB_EXTERN_C_BEG / ECB_EXTERN_C_END
127
128These two macros can be used to wrap multiple C<extern "C"> definitions -
129they expand to nothing in C.
130
131They are most useful in header files:
132
133 ECB_EXTERN_C_BEG
134
135 int mycfun1 (int x);
136 int mycfun2 (int x);
137
138 ECB_EXTERN_C_END
139
140=item ECB_STDFP
141
142If this evaluates to a true value (suitable for testing in by the
143preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
144and double/binary64 representations internally I<and> the endianness of
145both types match the endianness of C<uint32_t> and C<uint64_t>.
146
147This means you can just copy the bits of a C<float> (or C<double>) to an
148C<uint32_t> (or C<uint64_t>) and get the raw IEEE 754 bit representation
149without having to think about format or endianness.
150
151This is true for basically all modern platforms, although F<ecb.h> might
152not be able to deduce this correctly everywhere and might err on the safe
153side.
154
155=back
58 156
59=head2 GCC ATTRIBUTES 157=head2 GCC ATTRIBUTES
60 158
61A major part of libecb deals with GCC attributes. These are additional 159A major part of libecb deals with GCC attributes. These are additional
62attributes that you can assign to functions, variables and sometimes even 160attributes that you can assign to functions, variables and sometimes even
… …
138 } 236 }
139 237
140In this case, the compiler would probably be smart enough to deduce it on 238In this case, the compiler would probably be smart enough to deduce it on
141its own, so this is mainly useful for declarations. 239its own, so this is mainly useful for declarations.
142 240
241=item ecb_restrict
242
243Expands to the C<restrict> keyword or equivalent on compilers that support
244them, and to nothing on others. Must be specified on a pointer type or
245an array index to indicate that the memory doesn't alias with any other
246restricted pointer in the same scope.
247
248Example: multiply a vector, and allow the compiler to parallelise the
249loop, because it knows it doesn't overwrite input values.
250
251 void
252 multiply (float *ecb_restrict src,
253 float *ecb_restrict dst,
254 int len, float factor)
255 {
256 int i;
257
258 for (i = 0; i < len; ++i)
259 dst [i] = src [i] * factor;
260 }
261
143=item ecb_const 262=item ecb_const
144 263
145Declares that the function only depends on the values of its arguments, 264Declares that the function only depends on the values of its arguments,
146much like a mathematical function. It specifically does not read or write 265much like a mathematical function. It specifically does not read or write
147any memory any arguments might point to, global variables, or call any 266any memory any arguments might point to, global variables, or call any
… …
207functions only called in exceptional or rare cases. 326functions only called in exceptional or rare cases.
208 327
209=item ecb_artificial 328=item ecb_artificial
210 329
211Declares the function as "artificial", in this case meaning that this 330Declares the function as "artificial", in this case meaning that this
212function is not really mean to be a function, but more like an accessor 331function is not really meant to be a function, but more like an accessor
213- many methods in C++ classes are mere accessor functions, and having a 332- many methods in C++ classes are mere accessor functions, and having a
214crash reported in such a method, or single-stepping through them, is not 333crash reported in such a method, or single-stepping through them, is not
215usually so helpful, especially when it's inlined to just a few instructions. 334usually so helpful, especially when it's inlined to just a few instructions.
216 335
217Marking them as artificial will instruct the debugger about just this, 336Marking them as artificial will instruct the debugger about just this,
… …
425For example: 544For example:
426 545
427 ecb_ctz32 (3) = 0 546 ecb_ctz32 (3) = 0
428 ecb_ctz32 (6) = 1 547 ecb_ctz32 (6) = 1
429 548
549=item bool ecb_is_pot32 (uint32_t x)
550
551=item bool ecb_is_pot64 (uint32_t x)
552
553Return true iff C<x> is a power of two or C<x == 0>.
554
555For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
556
430=item int ecb_ld32 (uint32_t x) 557=item int ecb_ld32 (uint32_t x)
431 558
432=item int ecb_ld64 (uint64_t x) 559=item int ecb_ld64 (uint64_t x)
433 560
434Returns the index of the most significant bit set in C<x>, or the number 561Returns the index of the most significant bit set in C<x>, or the number
… …
455For example: 582For example:
456 583
457 ecb_popcount32 (7) = 3 584 ecb_popcount32 (7) = 3
458 ecb_popcount32 (255) = 8 585 ecb_popcount32 (255) = 8
459 586
587=item uint8_t ecb_bitrev8 (uint8_t x)
588
589=item uint16_t ecb_bitrev16 (uint16_t x)
590
591=item uint32_t ecb_bitrev32 (uint32_t x)
592
593Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
594and so on.
595
596Example:
597
598 ecb_bitrev8 (0xa7) = 0xea
599 ecb_bitrev32 (0xffcc4411) = 0x882233ff
600
460=item uint32_t ecb_bswap16 (uint32_t x) 601=item uint32_t ecb_bswap16 (uint32_t x)
461 602
462=item uint32_t ecb_bswap32 (uint32_t x) 603=item uint32_t ecb_bswap32 (uint32_t x)
463 604
464=item uint64_t ecb_bswap64 (uint64_t x) 605=item uint64_t ecb_bswap64 (uint64_t x)
… …
488(C<ecb_rotl>). 629(C<ecb_rotl>).
489 630
490Current GCC versions understand these functions and usually compile them 631Current GCC versions understand these functions and usually compile them
491to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 632to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
492x86). 633x86).
634
635=back
636
637=head2 FLOATING POINT FIDDLING
638
639=over 4
640
641=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
642
643=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
644
645These functions each take an argument in the native C<float> or C<double>
646type and return the IEEE 754 bit representation of it.
647
648The bit representation is just as IEEE 754 defines it, i.e. the sign bit
649will be the most significant bit, followed by exponent and mantissa.
650
651This function should work even when the native floating point format isn't
652IEEE compliant, of course at a speed and code size penalty, and of course
653also within reasonable limits (it tries to convert NaNs, infinities and
654denormals, but will likely convert negative zero to positive zero).
655
656On all modern platforms (where C<ECB_STDFP> is true), the compiler should
657be able to optimise away this function completely.
658
659These functions can be helpful when serialising floats to the network - you
660can serialise the return value like a normal uint32_t/uint64_t.
661
662Another use for these functions is to manipulate floating point values
663directly.
664
665Silly example: toggle the sign bit of a float.
666
667 /* On gcc-4.7 on amd64, */
668 /* this results in a single add instruction to toggle the bit, and 4 extra */
669 /* instructions to move the float value to an integer register and back. */
670
671 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
672
673=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
674
675=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM]
676
677The reverse operation of the previos function - takes the bit representation
678of an IEEE binary32 or binary64 number and converts it to the native C<float>
679or C<double> format.
680
681This function should work even when the native floating point format isn't
682IEEE compliant, of course at a speed and code size penalty, and of course
683also within reasonable limits (it tries to convert normals and denormals,
684and might be lucky for infinities, and with extraordinary luck, also for
685negative zero).
686
687On all modern platforms (where C<ECB_STDFP> is true), the compiler should
688be able to optimise away this function completely.
493 689
494=back 690=back
495 691
496=head2 ARITHMETIC 692=head2 ARITHMETIC
497 693
… …
548 for (i = 0; i < ecb_array_length (primes); i++) 744 for (i = 0; i < ecb_array_length (primes); i++)
549 sum += primes [i]; 745 sum += primes [i];
550 746
551=back 747=back
552 748
749=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
553 750
751These symbols need to be defined before including F<ecb.h> the first time.
752
753=over 4
754
755=item ECB_NO_THREADS
756
757If F<ecb.h> is never used from multiple threads, then this symbol can
758be defined, in which case memory fences (and similar constructs) are
759completely removed, leading to more efficient code and fewer dependencies.
760
761Setting this symbol to a true value implies C<ECB_NO_SMP>.
762
763=item ECB_NO_SMP
764
765The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
766multiple threads, but never concurrently (e.g. if the system the program
767runs on has only a single CPU with a single core, no hyperthreading and so
768on), then this symbol can be defined, leading to more efficient code and
769fewer dependencies.
770
771=item ECB_NO_LIBM
772
773When defined to C<1>, do not export any functions that might introduce
774dependencies on the math library (usually called F<-lm>) - these are
775marked with [-UECB_NO_LIBM].
776
777=back
778
779

Diff Legend

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