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

Comparing libecb/ecb.pod (file contents):
Revision 1.41 by root, Mon May 28 08:40:25 2012 UTC vs.
Revision 1.54 by root, Wed Dec 19 23:33:47 2012 UTC

… …
58 58
59=head2 TYPES / TYPE SUPPORT 59=head2 TYPES / TYPE SUPPORT
60 60
61ecb.h makes sure that the following types are defined (in the expected way): 61ecb.h makes sure that the following types are defined (in the expected way):
62 62
63 int8_t uint8_t int16_t uint16_t 63 int8_t uint8_t int16_t uint16_t
64 int32_t uint32_t int64_t uint64_t 64 int32_t uint32_t int64_t uint64_t
65 intptr_t uintptr_t 65 intptr_t uintptr_t
66 66
67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this 67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
68platform (currently C<4> or C<8>). 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=item ECB_AMD64, ECB_AMD64_X32
156
157These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32
158ABI, respectively, and undefined elsewhere.
159
160The designers of the new X32 ABI for some inexplicable reason decided to
161make it look exactly like amd64, even though it's completely incompatible
162to that ABI, breaking about every piece of software that assumed that
163C<__x86_64> stands for, well, the x86-64 ABI, making these macros
164necessary.
165
166=back
69 167
70=head2 GCC ATTRIBUTES 168=head2 GCC ATTRIBUTES
71 169
72A major part of libecb deals with GCC attributes. These are additional 170A major part of libecb deals with GCC attributes. These are additional
73attributes that you can assign to functions, variables and sometimes even 171attributes that you can assign to functions, variables and sometimes even
… …
149 } 247 }
150 248
151In this case, the compiler would probably be smart enough to deduce it on 249In this case, the compiler would probably be smart enough to deduce it on
152its own, so this is mainly useful for declarations. 250its own, so this is mainly useful for declarations.
153 251
252=item ecb_restrict
253
254Expands to the C<restrict> keyword or equivalent on compilers that support
255them, and to nothing on others. Must be specified on a pointer type or
256an array index to indicate that the memory doesn't alias with any other
257restricted pointer in the same scope.
258
259Example: multiply a vector, and allow the compiler to parallelise the
260loop, because it knows it doesn't overwrite input values.
261
262 void
263 multiply (float *ecb_restrict src,
264 float *ecb_restrict dst,
265 int len, float factor)
266 {
267 int i;
268
269 for (i = 0; i < len; ++i)
270 dst [i] = src [i] * factor;
271 }
272
154=item ecb_const 273=item ecb_const
155 274
156Declares that the function only depends on the values of its arguments, 275Declares that the function only depends on the values of its arguments,
157much like a mathematical function. It specifically does not read or write 276much like a mathematical function. It specifically does not read or write
158any memory any arguments might point to, global variables, or call any 277any memory any arguments might point to, global variables, or call any
… …
218functions only called in exceptional or rare cases. 337functions only called in exceptional or rare cases.
219 338
220=item ecb_artificial 339=item ecb_artificial
221 340
222Declares the function as "artificial", in this case meaning that this 341Declares the function as "artificial", in this case meaning that this
223function is not really mean to be a function, but more like an accessor 342function is not really meant to be a function, but more like an accessor
224- many methods in C++ classes are mere accessor functions, and having a 343- many methods in C++ classes are mere accessor functions, and having a
225crash reported in such a method, or single-stepping through them, is not 344crash reported in such a method, or single-stepping through them, is not
226usually so helpful, especially when it's inlined to just a few instructions. 345usually so helpful, especially when it's inlined to just a few instructions.
227 346
228Marking them as artificial will instruct the debugger about just this, 347Marking them as artificial will instruct the debugger about just this,
… …
524to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 643to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
525x86). 644x86).
526 645
527=back 646=back
528 647
648=head2 FLOATING POINT FIDDLING
649
650=over 4
651
652=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
653
654=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
655
656These functions each take an argument in the native C<float> or C<double>
657type and return the IEEE 754 bit representation of it.
658
659The bit representation is just as IEEE 754 defines it, i.e. the sign bit
660will be the most significant bit, followed by exponent and mantissa.
661
662This function should work even when the native floating point format isn't
663IEEE compliant, of course at a speed and code size penalty, and of course
664also within reasonable limits (it tries to convert NaNs, infinities and
665denormals, but will likely convert negative zero to positive zero).
666
667On all modern platforms (where C<ECB_STDFP> is true), the compiler should
668be able to optimise away this function completely.
669
670These functions can be helpful when serialising floats to the network - you
671can serialise the return value like a normal uint32_t/uint64_t.
672
673Another use for these functions is to manipulate floating point values
674directly.
675
676Silly example: toggle the sign bit of a float.
677
678 /* On gcc-4.7 on amd64, */
679 /* this results in a single add instruction to toggle the bit, and 4 extra */
680 /* instructions to move the float value to an integer register and back. */
681
682 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
683
684=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
685
686=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM]
687
688The reverse operation of the previos function - takes the bit representation
689of an IEEE binary32 or binary64 number and converts it to the native C<float>
690or C<double> format.
691
692This function should work even when the native floating point format isn't
693IEEE compliant, of course at a speed and code size penalty, and of course
694also within reasonable limits (it tries to convert normals and denormals,
695and might be lucky for infinities, and with extraordinary luck, also for
696negative zero).
697
698On all modern platforms (where C<ECB_STDFP> is true), the compiler should
699be able to optimise away this function completely.
700
701=back
702
529=head2 ARITHMETIC 703=head2 ARITHMETIC
530 704
531=over 4 705=over 4
532 706
533=item x = ecb_mod (m, n) 707=item x = ecb_mod (m, n)
… …
581 for (i = 0; i < ecb_array_length (primes); i++) 755 for (i = 0; i < ecb_array_length (primes); i++)
582 sum += primes [i]; 756 sum += primes [i];
583 757
584=back 758=back
585 759
760=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
586 761
762These symbols need to be defined before including F<ecb.h> the first time.
763
764=over 4
765
766=item ECB_NO_THREADS
767
768If F<ecb.h> is never used from multiple threads, then this symbol can
769be defined, in which case memory fences (and similar constructs) are
770completely removed, leading to more efficient code and fewer dependencies.
771
772Setting this symbol to a true value implies C<ECB_NO_SMP>.
773
774=item ECB_NO_SMP
775
776The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
777multiple threads, but never concurrently (e.g. if the system the program
778runs on has only a single CPU with a single core, no hyperthreading and so
779on), then this symbol can be defined, leading to more efficient code and
780fewer dependencies.
781
782=item ECB_NO_LIBM
783
784When defined to C<1>, do not export any functions that might introduce
785dependencies on the math library (usually called F<-lm>) - these are
786marked with [-UECB_NO_LIBM].
787
788=back
789
790

Diff Legend

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