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

Comparing libecb/ecb.pod (file contents):
Revision 1.48 by root, Wed May 30 16:56:06 2012 UTC vs.
Revision 1.71 by root, Sat Nov 21 16:53:50 2015 UTC

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 ptrdiff_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>) and can be used in preprocessor 68platform (currently C<4> or C<8>) and can be used in preprocessor
69expressions. 69expressions.
70 70
71For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
72
71=head2 LANGUAGE/COMPILER VERSIONS 73=head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
72 74
73All the following symbols expand to an expression that can be tested in 75All the following symbols expand to an expression that can be tested in
74preprocessor instructions as well as treated as a boolean (use C<!!> to 76preprocessor instructions as well as treated as a boolean (use C<!!> to
75ensure it's either C<0> or C<1> if you need that). 77ensure it's either C<0> or C<1> if you need that).
76 78
77=over 4 79=over 4
78 80
79=item ECB_C 81=item ECB_C
80 82
81True if the implementation defines the C<__STDC__> macro to a true value, 83True if the implementation defines the C<__STDC__> macro to a true value,
82which is typically true for both C and C++ compilers. 84while not claiming to be C++.
83 85
84=item ECB_C99 86=item ECB_C99
85 87
86True if the implementation claims to be compliant to C99 (ISO/IEC 88True if the implementation claims to be compliant to C99 (ISO/IEC
879899:1999) or any later version. 899899:1999) or any later version, while not claiming to be C++.
88 90
89Note that later versions (ECB_C11) remove core features again (for 91Note that later versions (ECB_C11) remove core features again (for
90example, variable length arrays). 92example, variable length arrays).
91 93
92=item ECB_C11 94=item ECB_C11
93 95
94True if the implementation claims to be compliant to C11 (ISO/IEC 96True if the implementation claims to be compliant to C11 (ISO/IEC
959899:2011) or any later version. 979899:2011) or any later version, while not claiming to be C++.
96 98
97=item ECB_CPP 99=item ECB_CPP
98 100
99True if the implementation defines the C<__cplusplus__> macro to a true 101True if the implementation defines the C<__cplusplus__> macro to a true
100value, which is typically true for C++ compilers. 102value, which is typically true for C++ compilers.
102=item ECB_CPP11 104=item ECB_CPP11
103 105
104True if the implementation claims to be compliant to ISO/IEC 14882:2011 106True if the implementation claims to be compliant to ISO/IEC 14882:2011
105(C++11) or any later version. 107(C++11) or any later version.
106 108
107=item ECB_GCC_VERSION(major,minor) 109=item ECB_GCC_VERSION (major, minor)
108 110
109Expands to a true value (suitable for testing in by the preprocessor) 111Expands to a true value (suitable for testing in by the preprocessor)
110if the compiler used is GNU C and the version is the given version, or 112if the compiler used is GNU C and the version is the given version, or
111higher. 113higher.
112 114
113This macro tries to return false on compilers that claim to be GCC 115This macro tries to return false on compilers that claim to be GCC
114compatible but aren't. 116compatible but aren't.
115 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
116=back 166=back
117 167
168=head2 MACRO TRICKERY
169
170=over 4
171
172=item ECB_CONCAT (a, b)
173
174Expands any macros in C<a> and C<b>, then concatenates the result to form
175a single token. This is mainly useful to form identifiers from components,
176e.g.:
177
178 #define S1 str
179 #define S2 cpy
180
181 ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
182
183=item ECB_STRINGIFY (arg)
184
185Expands any macros in C<arg> and returns the stringified version of
186it. This is mainly useful to get the contents of a macro in string form,
187e.g.:
188
189 #define SQL_LIMIT 100
190 sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
191
192=item ECB_STRINGIFY_EXPR (expr)
193
194Like C<ECB_STRINGIFY>, but additionally evaluates C<expr> to make sure it
195is a valid expression. This is useful to catch typos or cases where the
196macro isn't available:
197
198 #include <errno.h>
199
200 ECB_STRINGIFY (EDOM); // "33" (on my system at least)
201 ECB_STRINGIFY_EXPR (EDOM); // "33"
202
203 // now imagine we had a typo:
204
205 ECB_STRINGIFY (EDAM); // "EDAM"
206 ECB_STRINGIFY_EXPR (EDAM); // error: EDAM undefined
207
208=back
209
118=head2 GCC ATTRIBUTES 210=head2 ATTRIBUTES
119 211
120A major part of libecb deals with GCC attributes. These are additional 212A major part of libecb deals with additional attributes that can be
121attributes that you can assign to functions, variables and sometimes even 213assigned to functions, variables and sometimes even types - much like
122types - much like C<const> or C<volatile> in C. 214C<const> or C<volatile> in C. They are implemented using either GCC
123 215attributes or other compiler/language specific features. Attributes
124While GCC allows declarations to show up in many surprising places,
125but not in many expected places, the safest way is to put attribute
126declarations before the whole declaration: 216declarations must be put before the whole declaration:
127 217
128 ecb_const int mysqrt (int a); 218 ecb_const int mysqrt (int a);
129 ecb_unused int i; 219 ecb_unused int i;
130 220
131For variables, it is often nicer to put the attribute after the name, and
132avoid multiple declarations using commas:
133
134 int i ecb_unused;
135
136=over 4 221=over 4
137
138=item ecb_attribute ((attrs...))
139
140A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
141nothing on other compilers, so the effect is that only GCC sees these.
142
143Example: use the C<deprecated> attribute on a function.
144
145 ecb_attribute((__deprecated__)) void
146 do_not_use_me_anymore (void);
147 222
148=item ecb_unused 223=item ecb_unused
149 224
150Marks a function or a variable as "unused", which simply suppresses a 225Marks a function or a variable as "unused", which simply suppresses a
151warning by GCC when it detects it as unused. This is useful when you e.g. 226warning by GCC when it detects it as unused. This is useful when you e.g.
152declare a variable but do not always use it: 227declare a variable but do not always use it:
153 228
154 { 229 {
155 int var ecb_unused; 230 ecb_unused int var;
156 231
157 #ifdef SOMECONDITION 232 #ifdef SOMECONDITION
158 var = ...; 233 var = ...;
159 return var; 234 return var;
160 #else 235 #else
161 return 0; 236 return 0;
162 #endif 237 #endif
163 } 238 }
164 239
240=item ecb_deprecated
241
242Similar to C<ecb_unused>, but marks a function, variable or type as
243deprecated. This makes some compilers warn when the type is used.
244
245=item ecb_deprecated_message (message)
246
247Same as C<ecb_deprecated>, but if possible, the specified diagnostic is
248used instead of a generic depreciation message when the object is being
249used.
250
165=item ecb_inline 251=item ecb_inline
166 252
167This is not actually an attribute, but you use it like one. It expands
168either to C<static inline> or to just C<static>, if inline isn't 253Expands either to C<static inline> or to just C<static>, if inline
169supported. It should be used to declare functions that should be inlined, 254isn't supported. It should be used to declare functions that should be
170for code size or speed reasons. 255inlined, for code size or speed reasons.
171 256
172Example: inline this function, it surely will reduce codesize. 257Example: inline this function, it surely will reduce codesize.
173 258
174 ecb_inline int 259 ecb_inline int
175 negmul (int a, int b) 260 negmul (int a, int b)
177 return - (a * b); 262 return - (a * b);
178 } 263 }
179 264
180=item ecb_noinline 265=item ecb_noinline
181 266
182Prevent a function from being inlined - it might be optimised away, but 267Prevents a function from being inlined - it might be optimised away, but
183not inlined into other functions. This is useful if you know your function 268not inlined into other functions. This is useful if you know your function
184is rarely called and large enough for inlining not to be helpful. 269is rarely called and large enough for inlining not to be helpful.
185 270
186=item ecb_noreturn 271=item ecb_noreturn
187 272
197 } 282 }
198 283
199In this case, the compiler would probably be smart enough to deduce it on 284In this case, the compiler would probably be smart enough to deduce it on
200its own, so this is mainly useful for declarations. 285its own, so this is mainly useful for declarations.
201 286
287=item ecb_restrict
288
289Expands to the C<restrict> keyword or equivalent on compilers that support
290them, and to nothing on others. Must be specified on a pointer type or
291an array index to indicate that the memory doesn't alias with any other
292restricted pointer in the same scope.
293
294Example: multiply a vector, and allow the compiler to parallelise the
295loop, because it knows it doesn't overwrite input values.
296
297 void
298 multiply (ecb_restrict float *src,
299 ecb_restrict float *dst,
300 int len, float factor)
301 {
302 int i;
303
304 for (i = 0; i < len; ++i)
305 dst [i] = src [i] * factor;
306 }
307
202=item ecb_const 308=item ecb_const
203 309
204Declares that the function only depends on the values of its arguments, 310Declares that the function only depends on the values of its arguments,
205much like a mathematical function. It specifically does not read or write 311much like a mathematical function. It specifically does not read or write
206any memory any arguments might point to, global variables, or call any 312any memory any arguments might point to, global variables, or call any
266functions only called in exceptional or rare cases. 372functions only called in exceptional or rare cases.
267 373
268=item ecb_artificial 374=item ecb_artificial
269 375
270Declares the function as "artificial", in this case meaning that this 376Declares the function as "artificial", in this case meaning that this
271function is not really mean to be a function, but more like an accessor 377function is not really meant to be a function, but more like an accessor
272- many methods in C++ classes are mere accessor functions, and having a 378- many methods in C++ classes are mere accessor functions, and having a
273crash reported in such a method, or single-stepping through them, is not 379crash reported in such a method, or single-stepping through them, is not
274usually so helpful, especially when it's inlined to just a few instructions. 380usually so helpful, especially when it's inlined to just a few instructions.
275 381
276Marking them as artificial will instruct the debugger about just this, 382Marking them as artificial will instruct the debugger about just this,
296 402
297=head2 OPTIMISATION HINTS 403=head2 OPTIMISATION HINTS
298 404
299=over 4 405=over 4
300 406
301=item bool ecb_is_constant(expr) 407=item bool ecb_is_constant (expr)
302 408
303Returns true iff the expression can be deduced to be a compile-time 409Returns true iff the expression can be deduced to be a compile-time
304constant, and false otherwise. 410constant, and false otherwise.
305 411
306For example, when you have a C<rndm16> function that returns a 16 bit 412For example, when you have a C<rndm16> function that returns a 16 bit
324 return is_constant (n) && !(n & (n - 1)) 430 return is_constant (n) && !(n & (n - 1))
325 ? rndm16 () & (num - 1) 431 ? rndm16 () & (num - 1)
326 : (n * (uint32_t)rndm16 ()) >> 16; 432 : (n * (uint32_t)rndm16 ()) >> 16;
327 } 433 }
328 434
329=item bool ecb_expect (expr, value) 435=item ecb_expect (expr, value)
330 436
331Evaluates C<expr> and returns it. In addition, it tells the compiler that 437Evaluates C<expr> and returns it. In addition, it tells the compiler that
332the C<expr> evaluates to C<value> a lot, which can be used for static 438the C<expr> evaluates to C<value> a lot, which can be used for static
333branch optimisations. 439branch optimisations.
334 440
381 { 487 {
382 if (ecb_expect_false (current + size > end)) 488 if (ecb_expect_false (current + size > end))
383 real_reserve_method (size); /* presumably noinline */ 489 real_reserve_method (size); /* presumably noinline */
384 } 490 }
385 491
386=item bool ecb_assume (cond) 492=item ecb_assume (cond)
387 493
388Try to tell the compiler that some condition is true, even if it's not 494Tries to tell the compiler that some condition is true, even if it's not
389obvious. 495obvious. This is not a function, but a statement: it cannot be used in
496another expression.
390 497
391This can be used to teach the compiler about invariants or other 498This can be used to teach the compiler about invariants or other
392conditions that might improve code generation, but which are impossible to 499conditions that might improve code generation, but which are impossible to
393deduce form the code itself. 500deduce form the code itself.
394 501
411 518
412Then the compiler I<might> be able to optimise out the second call 519Then the compiler I<might> be able to optimise out the second call
413completely, as it knows that C<< current + 1 > end >> is false and the 520completely, as it knows that C<< current + 1 > end >> is false and the
414call will never be executed. 521call will never be executed.
415 522
416=item bool ecb_unreachable () 523=item ecb_unreachable ()
417 524
418This function does nothing itself, except tell the compiler that it will 525This function does nothing itself, except tell the compiler that it will
419never be executed. Apart from suppressing a warning in some cases, this 526never be executed. Apart from suppressing a warning in some cases, this
420function can be used to implement C<ecb_assume> or similar functions. 527function can be used to implement C<ecb_assume> or similar functionality.
421 528
422=item bool ecb_prefetch (addr, rw, locality) 529=item ecb_prefetch (addr, rw, locality)
423 530
424Tells the compiler to try to prefetch memory at the given C<addr>ess 531Tells the compiler to try to prefetch memory at the given C<addr>ess
425for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of 532for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
426C<0> means that there will only be one access later, C<3> means that 533C<0> means that there will only be one access later, C<3> means that
427the data will likely be accessed very often, and values in between mean 534the data will likely be accessed very often, and values in between mean
428something... in between. The memory pointed to by the address does not 535something... in between. The memory pointed to by the address does not
429need to be accessible (it could be a null pointer for example), but C<rw> 536need to be accessible (it could be a null pointer for example), but C<rw>
430and C<locality> must be compile-time constants. 537and C<locality> must be compile-time constants.
431 538
539This is a statement, not a function: you cannot use it as part of an
540expression.
541
432An obvious way to use this is to prefetch some data far away, in a big 542An obvious way to use this is to prefetch some data far away, in a big
433array you loop over. This prefetches memory some 128 array elements later, 543array you loop over. This prefetches memory some 128 array elements later,
434in the hope that it will be ready when the CPU arrives at that location. 544in the hope that it will be ready when the CPU arrives at that location.
435 545
436 int sum = 0; 546 int sum = 0;
488 598
489=item bool ecb_is_pot32 (uint32_t x) 599=item bool ecb_is_pot32 (uint32_t x)
490 600
491=item bool ecb_is_pot64 (uint32_t x) 601=item bool ecb_is_pot64 (uint32_t x)
492 602
493Return true iff C<x> is a power of two or C<x == 0>. 603Returns true iff C<x> is a power of two or C<x == 0>.
494 604
495For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>. 605For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
496 606
497=item int ecb_ld32 (uint32_t x) 607=item int ecb_ld32 (uint32_t x)
498 608
499=item int ecb_ld64 (uint64_t x) 609=item int ecb_ld64 (uint64_t x)
500 610
569(C<ecb_rotl>). 679(C<ecb_rotl>).
570 680
571Current GCC versions understand these functions and usually compile them 681Current GCC versions understand these functions and usually compile them
572to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 682to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
573x86). 683x86).
684
685=back
686
687=head2 FLOATING POINT FIDDLING
688
689=over 4
690
691=item ECB_INFINITY [-UECB_NO_LIBM]
692
693Evaluates to positive infinity if supported by the platform, otherwise to
694a truly huge number.
695
696=item ECB_NAN [-UECB_NO_LIBM]
697
698Evaluates to a quiet NAN if supported by the platform, otherwise to
699C<ECB_INFINITY>.
700
701=item float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
702
703Same as C<ldexpf>, but always available.
704
705=item uint32_t ecb_float_to_binary16 (float x) [-UECB_NO_LIBM]
706
707=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
708
709=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
710
711These functions each take an argument in the native C<float> or C<double>
712type and return the IEEE 754 bit representation of it (binary16/half,
713binary32/single or binary64/double precision).
714
715The bit representation is just as IEEE 754 defines it, i.e. the sign bit
716will be the most significant bit, followed by exponent and mantissa.
717
718This function should work even when the native floating point format isn't
719IEEE compliant, of course at a speed and code size penalty, and of course
720also within reasonable limits (it tries to convert NaNs, infinities and
721denormals, but will likely convert negative zero to positive zero).
722
723On all modern platforms (where C<ECB_STDFP> is true), the compiler should
724be able to optimise away this function completely.
725
726These functions can be helpful when serialising floats to the network - you
727can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
728
729Another use for these functions is to manipulate floating point values
730directly.
731
732Silly example: toggle the sign bit of a float.
733
734 /* On gcc-4.7 on amd64, */
735 /* this results in a single add instruction to toggle the bit, and 4 extra */
736 /* instructions to move the float value to an integer register and back. */
737
738 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
739
740=item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM]
741
742=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
743
744=item double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
745
746The reverse operation of the previous function - takes the bit
747representation of an IEEE binary16, binary32 or binary64 number (half,
748single or double precision) and converts it to the native C<float> or
749C<double> format.
750
751This function should work even when the native floating point format isn't
752IEEE compliant, of course at a speed and code size penalty, and of course
753also within reasonable limits (it tries to convert normals and denormals,
754and might be lucky for infinities, and with extraordinary luck, also for
755negative zero).
756
757On all modern platforms (where C<ECB_STDFP> is true), the compiler should
758be able to optimise away this function completely.
759
760=item uint16_t ecb_binary32_to_binary16 (uint32_t x)
761
762=item uint32_t ecb_binary16_to_binary32 (uint16_t x)
763
764Convert a IEEE binary32/single precision to binary16/half format, and vice
765versa, handling all details (round-to-even, subnormals, infinity and NaNs)
766correctly.
767
768These are functions are available under C<-DECB_NO_LIBM>, since
769they do not rely on the platform floating point format. The
770C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
771usually what you want.
574 772
575=back 773=back
576 774
577=head2 ARITHMETIC 775=head2 ARITHMETIC
578 776
635 833
636These symbols need to be defined before including F<ecb.h> the first time. 834These symbols need to be defined before including F<ecb.h> the first time.
637 835
638=over 4 836=over 4
639 837
640=item ECB_NO_THRADS 838=item ECB_NO_THREADS
641 839
642If F<ecb.h> is never used from multiple threads, then this symbol can 840If F<ecb.h> is never used from multiple threads, then this symbol can
643be defined, in which case memory fences (and similar constructs) are 841be defined, in which case memory fences (and similar constructs) are
644completely removed, leading to more efficient code and fewer dependencies. 842completely removed, leading to more efficient code and fewer dependencies.
645 843
651multiple threads, but never concurrently (e.g. if the system the program 849multiple threads, but never concurrently (e.g. if the system the program
652runs on has only a single CPU with a single core, no hyperthreading and so 850runs on has only a single CPU with a single core, no hyperthreading and so
653on), then this symbol can be defined, leading to more efficient code and 851on), then this symbol can be defined, leading to more efficient code and
654fewer dependencies. 852fewer dependencies.
655 853
854=item ECB_NO_LIBM
855
856When defined to C<1>, do not export any functions that might introduce
857dependencies on the math library (usually called F<-lm>) - these are
858marked with [-UECB_NO_LIBM].
859
656=back 860=back
657 861
862=head1 UNDOCUMENTED FUNCTIONALITY
658 863
864F<ecb.h> is full of undocumented functionality as well, some of which is
865intended to be internal-use only, some of which we forgot to document, and
866some of which we hide because we are not sure we will keep the interface
867stable.
868
869While you are welcome to rummage around and use whatever you find useful
870(we can't stop you), keep in mind that we will change undocumented
871functionality in incompatible ways without thinking twice, while we are
872considerably more conservative with documented things.
873
874=head1 AUTHORS
875
876C<libecb> is designed and maintained by:
877
878 Emanuele Giaquinta <e.giaquinta@glauco.it>
879 Marc Alexander Lehmann <schmorp@schmorp.de>
880
881

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines