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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.27 by root, Wed Jun 1 01:29:36 2011 UTC vs.
Revision 1.56 by root, Mon Jun 9 17:31:57 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
… …
101 #else 210 #else
102 return 0; 211 return 0;
103 #endif 212 #endif
104 } 213 }
105 214
215=item ecb_deprecated
216
217Similar to C<ecb_unused>, but marks a function, variable or type as
218deprecated. This makes some compilers warn when the type is used.
219
220=item ecb_inline
221
222This is not actually an attribute, but you use it like one. It expands
223either to C<static inline> or to just C<static>, if inline isn't
224supported. It should be used to declare functions that should be inlined,
225for code size or speed reasons.
226
227Example: inline this function, it surely will reduce codesize.
228
229 ecb_inline int
230 negmul (int a, int b)
231 {
232 return - (a * b);
233 }
234
106=item ecb_noinline 235=item ecb_noinline
107 236
108Prevent a function from being inlined - it might be optimised away, but 237Prevent a function from being inlined - it might be optimised away, but
109not inlined into other functions. This is useful if you know your function 238not inlined into other functions. This is useful if you know your function
110is rarely called and large enough for inlining not to be helpful. 239is rarely called and large enough for inlining not to be helpful.
… …
123 } 252 }
124 253
125In this case, the compiler would probably be smart enough to deduce it on 254In this case, the compiler would probably be smart enough to deduce it on
126its own, so this is mainly useful for declarations. 255its own, so this is mainly useful for declarations.
127 256
257=item ecb_restrict
258
259Expands to the C<restrict> keyword or equivalent on compilers that support
260them, and to nothing on others. Must be specified on a pointer type or
261an array index to indicate that the memory doesn't alias with any other
262restricted pointer in the same scope.
263
264Example: multiply a vector, and allow the compiler to parallelise the
265loop, because it knows it doesn't overwrite input values.
266
267 void
268 multiply (float *ecb_restrict src,
269 float *ecb_restrict dst,
270 int len, float factor)
271 {
272 int i;
273
274 for (i = 0; i < len; ++i)
275 dst [i] = src [i] * factor;
276 }
277
128=item ecb_const 278=item ecb_const
129 279
130Declares that the function only depends on the values of its arguments, 280Declares that the function only depends on the values of its arguments,
131much like a mathematical function. It specifically does not read or write 281much like a mathematical function. It specifically does not read or write
132any memory any arguments might point to, global variables, or call any 282any memory any arguments might point to, global variables, or call any
… …
192functions only called in exceptional or rare cases. 342functions only called in exceptional or rare cases.
193 343
194=item ecb_artificial 344=item ecb_artificial
195 345
196Declares the function as "artificial", in this case meaning that this 346Declares the function as "artificial", in this case meaning that this
197function is not really mean to be a function, but more like an accessor 347function is not really meant to be a function, but more like an accessor
198- many methods in C++ classes are mere accessor functions, and having a 348- many methods in C++ classes are mere accessor functions, and having a
199crash reported in such a method, or single-stepping through them, is not 349crash reported in such a method, or single-stepping through them, is not
200usually so helpful, especially when it's inlined to just a few instructions. 350usually so helpful, especially when it's inlined to just a few instructions.
201 351
202Marking them as artificial will instruct the debugger about just this, 352Marking them as artificial will instruct the debugger about just this,
… …
381After processing the node, (part of) the next node might already be in 531After processing the node, (part of) the next node might already be in
382cache. 532cache.
383 533
384=back 534=back
385 535
386=head2 BIT FIDDLING / BITSTUFFS 536=head2 BIT FIDDLING / BIT WIZARDRY
387 537
388=over 4 538=over 4
389 539
390=item bool ecb_big_endian () 540=item bool ecb_big_endian ()
391 541
… …
397 547
398On systems that are neither, their return values are unspecified. 548On systems that are neither, their return values are unspecified.
399 549
400=item int ecb_ctz32 (uint32_t x) 550=item int ecb_ctz32 (uint32_t x)
401 551
552=item int ecb_ctz64 (uint64_t x)
553
402Returns the index of the least significant bit set in C<x> (or 554Returns the index of the least significant bit set in C<x> (or
403equivalently the number of bits set to 0 before the least significant bit 555equivalently the number of bits set to 0 before the least significant bit
404set), starting from 0. If C<x> is 0 the result is undefined. A common use 556set), starting from 0. If C<x> is 0 the result is undefined.
405case is to compute the integer binary logarithm, i.e., C<floor (log2 557
558For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
559
406(n))>. For example: 560For example:
407 561
408 ecb_ctz32 (3) = 0 562 ecb_ctz32 (3) = 0
409 ecb_ctz32 (6) = 1 563 ecb_ctz32 (6) = 1
410 564
565=item bool ecb_is_pot32 (uint32_t x)
566
567=item bool ecb_is_pot64 (uint32_t x)
568
569Return true iff C<x> is a power of two or C<x == 0>.
570
571For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
572
573=item int ecb_ld32 (uint32_t x)
574
575=item int ecb_ld64 (uint64_t x)
576
577Returns the index of the most significant bit set in C<x>, or the number
578of digits the number requires in binary (so that C<< 2**ld <= x <
5792**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
580to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
581example to see how many bits a certain number requires to be encoded.
582
583This function is similar to the "count leading zero bits" function, except
584that that one returns how many zero bits are "in front" of the number (in
585the given data type), while C<ecb_ld> returns how many bits the number
586itself requires.
587
588For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
589
411=item int ecb_popcount32 (uint32_t x) 590=item int ecb_popcount32 (uint32_t x)
412 591
592=item int ecb_popcount64 (uint64_t x)
593
413Returns the number of bits set to 1 in C<x>. For example: 594Returns the number of bits set to 1 in C<x>.
595
596For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
597
598For example:
414 599
415 ecb_popcount32 (7) = 3 600 ecb_popcount32 (7) = 3
416 ecb_popcount32 (255) = 8 601 ecb_popcount32 (255) = 8
417 602
603=item uint8_t ecb_bitrev8 (uint8_t x)
604
605=item uint16_t ecb_bitrev16 (uint16_t x)
606
607=item uint32_t ecb_bitrev32 (uint32_t x)
608
609Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
610and so on.
611
612Example:
613
614 ecb_bitrev8 (0xa7) = 0xea
615 ecb_bitrev32 (0xffcc4411) = 0x882233ff
616
418=item uint32_t ecb_bswap16 (uint32_t x) 617=item uint32_t ecb_bswap16 (uint32_t x)
419 618
420=item uint32_t ecb_bswap32 (uint32_t x) 619=item uint32_t ecb_bswap32 (uint32_t x)
421 620
621=item uint64_t ecb_bswap64 (uint64_t x)
622
422These two functions return the value of the 16-bit (32-bit) value C<x> 623These functions return the value of the 16-bit (32-bit, 64-bit) value
423after reversing the order of bytes (0x11223344 becomes 0x44332211). 624C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
625C<ecb_bswap32>).
626
627=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
628
629=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
630
631=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
632
633=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
634
635=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
636
637=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
424 638
425=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count) 639=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
426 640
427=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count) 641=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
428 642
429These two functions return the value of C<x> after rotating all the bits 643These two families of functions return the value of C<x> after rotating
430by C<count> positions to the right or left respectively. 644all the bits by C<count> positions to the right (C<ecb_rotr>) or left
645(C<ecb_rotl>).
431 646
432Current GCC versions understand these functions and usually compile them 647Current GCC versions understand these functions and usually compile them
433to "optimal" code (e.g. a single C<roll> on x86). 648to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
649x86).
650
651=back
652
653=head2 FLOATING POINT FIDDLING
654
655=over 4
656
657=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
658
659=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
660
661These functions each take an argument in the native C<float> or C<double>
662type and return the IEEE 754 bit representation of it.
663
664The bit representation is just as IEEE 754 defines it, i.e. the sign bit
665will be the most significant bit, followed by exponent and mantissa.
666
667This function should work even when the native floating point format isn't
668IEEE compliant, of course at a speed and code size penalty, and of course
669also within reasonable limits (it tries to convert NaNs, infinities and
670denormals, but will likely convert negative zero to positive zero).
671
672On all modern platforms (where C<ECB_STDFP> is true), the compiler should
673be able to optimise away this function completely.
674
675These functions can be helpful when serialising floats to the network - you
676can serialise the return value like a normal uint32_t/uint64_t.
677
678Another use for these functions is to manipulate floating point values
679directly.
680
681Silly example: toggle the sign bit of a float.
682
683 /* On gcc-4.7 on amd64, */
684 /* this results in a single add instruction to toggle the bit, and 4 extra */
685 /* instructions to move the float value to an integer register and back. */
686
687 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
688
689=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
690
691=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM]
692
693The reverse operation of the previos function - takes the bit representation
694of an IEEE binary32 or binary64 number and converts it to the native C<float>
695or C<double> format.
696
697This function should work even when the native floating point format isn't
698IEEE compliant, of course at a speed and code size penalty, and of course
699also within reasonable limits (it tries to convert normals and denormals,
700and might be lucky for infinities, and with extraordinary luck, also for
701negative zero).
702
703On all modern platforms (where C<ECB_STDFP> is true), the compiler should
704be able to optimise away this function completely.
434 705
435=back 706=back
436 707
437=head2 ARITHMETIC 708=head2 ARITHMETIC
438 709
… …
448C<ecb_mod> implements the mathematical modulo operation, which is missing 719C<ecb_mod> implements the mathematical modulo operation, which is missing
449in the language. 720in the language.
450 721
451C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be 722C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
452negatable, that is, both C<m> and C<-m> must be representable in its 723negatable, that is, both C<m> and C<-m> must be representable in its
453type (this typically includes the minimum signed integer value, the same 724type (this typically excludes the minimum signed integer value, the same
454limitation as for C</> and C<%> in C). 725limitation as for C</> and C<%> in C).
455 726
456Current GCC versions compile this into an efficient branchless sequence on 727Current GCC versions compile this into an efficient branchless sequence on
457many systems. 728almost all CPUs.
458 729
459For example, when you want to rotate forward through the members of an 730For example, when you want to rotate forward through the members of an
460array for increasing C<m> (which might be negative), then you should use 731array for increasing C<m> (which might be negative), then you should use
461C<ecb_mod>, as the C<%> operator might give either negative results, or 732C<ecb_mod>, as the C<%> operator might give either negative results, or
462change direction for negative values: 733change direction for negative values:
463 734
464 for (m = -100; m <= 100; ++m) 735 for (m = -100; m <= 100; ++m)
465 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))]; 736 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
466 737
738=item x = ecb_div_rd (val, div)
739
740=item x = ecb_div_ru (val, div)
741
742Returns C<val> divided by C<div> rounded down or up, respectively.
743C<val> and C<div> must have integer types and C<div> must be strictly
744positive. Note that these functions are implemented with macros in C
745and with function templates in C++.
746
467=back 747=back
468 748
469=head2 UTILITY 749=head2 UTILITY
470 750
471=over 4 751=over 4
… …
480 for (i = 0; i < ecb_array_length (primes); i++) 760 for (i = 0; i < ecb_array_length (primes); i++)
481 sum += primes [i]; 761 sum += primes [i];
482 762
483=back 763=back
484 764
765=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
485 766
767These symbols need to be defined before including F<ecb.h> the first time.
768
769=over 4
770
771=item ECB_NO_THREADS
772
773If F<ecb.h> is never used from multiple threads, then this symbol can
774be defined, in which case memory fences (and similar constructs) are
775completely removed, leading to more efficient code and fewer dependencies.
776
777Setting this symbol to a true value implies C<ECB_NO_SMP>.
778
779=item ECB_NO_SMP
780
781The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
782multiple threads, but never concurrently (e.g. if the system the program
783runs on has only a single CPU with a single core, no hyperthreading and so
784on), then this symbol can be defined, leading to more efficient code and
785fewer dependencies.
786
787=item ECB_NO_LIBM
788
789When defined to C<1>, do not export any functions that might introduce
790dependencies on the math library (usually called F<-lm>) - these are
791marked with [-UECB_NO_LIBM].
792
793=back
794
795

Diff Legend

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