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.55 by root, Thu Jan 9 05:16:12 2014 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,
84while not claiming to be C++.
85
86=item ECB_C99
87
88True if the implementation claims to be compliant to C99 (ISO/IEC
899899:1999) or any later version, while not claiming to be C++.
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, while not claiming to be C++.
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
58 167
59=head2 GCC ATTRIBUTES 168=head2 GCC ATTRIBUTES
60 169
61A major part of libecb deals with GCC attributes. These are additional 170A major part of libecb deals with GCC attributes. These are additional
62attributes that you can assign to functions, variables and sometimes even 171attributes that you can assign to functions, variables and sometimes even
… …
138 } 247 }
139 248
140In 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
141its own, so this is mainly useful for declarations. 250its own, so this is mainly useful for declarations.
142 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
143=item ecb_const 273=item ecb_const
144 274
145Declares that the function only depends on the values of its arguments, 275Declares that the function only depends on the values of its arguments,
146much like a mathematical function. It specifically does not read or write 276much like a mathematical function. It specifically does not read or write
147any memory any arguments might point to, global variables, or call any 277any memory any arguments might point to, global variables, or call any
… …
207functions only called in exceptional or rare cases. 337functions only called in exceptional or rare cases.
208 338
209=item ecb_artificial 339=item ecb_artificial
210 340
211Declares the function as "artificial", in this case meaning that this 341Declares the function as "artificial", in this case meaning that this
212function 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
213- 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
214crash 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
215usually 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.
216 346
217Marking them as artificial will instruct the debugger about just this, 347Marking them as artificial will instruct the debugger about just this,
… …
425For example: 555For example:
426 556
427 ecb_ctz32 (3) = 0 557 ecb_ctz32 (3) = 0
428 ecb_ctz32 (6) = 1 558 ecb_ctz32 (6) = 1
429 559
560=item bool ecb_is_pot32 (uint32_t x)
561
562=item bool ecb_is_pot64 (uint32_t x)
563
564Return true iff C<x> is a power of two or C<x == 0>.
565
566For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
567
430=item int ecb_ld32 (uint32_t x) 568=item int ecb_ld32 (uint32_t x)
431 569
432=item int ecb_ld64 (uint64_t x) 570=item int ecb_ld64 (uint64_t x)
433 571
434Returns the index of the most significant bit set in C<x>, or the number 572Returns the index of the most significant bit set in C<x>, or the number
… …
455For example: 593For example:
456 594
457 ecb_popcount32 (7) = 3 595 ecb_popcount32 (7) = 3
458 ecb_popcount32 (255) = 8 596 ecb_popcount32 (255) = 8
459 597
598=item uint8_t ecb_bitrev8 (uint8_t x)
599
600=item uint16_t ecb_bitrev16 (uint16_t x)
601
602=item uint32_t ecb_bitrev32 (uint32_t x)
603
604Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
605and so on.
606
607Example:
608
609 ecb_bitrev8 (0xa7) = 0xea
610 ecb_bitrev32 (0xffcc4411) = 0x882233ff
611
460=item uint32_t ecb_bswap16 (uint32_t x) 612=item uint32_t ecb_bswap16 (uint32_t x)
461 613
462=item uint32_t ecb_bswap32 (uint32_t x) 614=item uint32_t ecb_bswap32 (uint32_t x)
463 615
464=item uint64_t ecb_bswap64 (uint64_t x) 616=item uint64_t ecb_bswap64 (uint64_t x)
… …
488(C<ecb_rotl>). 640(C<ecb_rotl>).
489 641
490Current GCC versions understand these functions and usually compile them 642Current 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 643to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
492x86). 644x86).
645
646=back
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.
493 700
494=back 701=back
495 702
496=head2 ARITHMETIC 703=head2 ARITHMETIC
497 704
… …
548 for (i = 0; i < ecb_array_length (primes); i++) 755 for (i = 0; i < ecb_array_length (primes); i++)
549 sum += primes [i]; 756 sum += primes [i];
550 757
551=back 758=back
552 759
760=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
553 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