ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
Revision: 1.86
Committed: Thu Apr 30 23:24:45 2020 UTC (4 years, 1 month ago) by root
Branch: MAIN
Changes since 1.85: +2 -0 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 =head1 LIBECB - e-C-Builtins
2
3 =head2 ABOUT LIBECB
4
5 Libecb is currently a simple header file that doesn't require any
6 configuration to use or include in your project.
7
8 It's part of the e-suite of libraries, other members of which include
9 libev and libeio.
10
11 Its homepage can be found here:
12
13 http://software.schmorp.de/pkg/libecb
14
15 It mainly provides a number of wrappers around many compiler built-ins,
16 together with replacement functions for other compilers. In addition
17 to this, it provides a number of other lowlevel C utilities, such as
18 endianness detection, byte swapping or bit rotations.
19
20 Or in other words, things that should be built into any standard C
21 system, but aren't, implemented as efficient as possible with GCC (clang,
22 msvc...), and still correct with other compilers.
23
24 More might come.
25
26 =head2 ABOUT THE HEADER
27
28 At the moment, all you have to do is copy F<ecb.h> somewhere where your
29 compiler can find it and include it:
30
31 #include <ecb.h>
32
33 The header should work fine for both C and C++ compilation, and gives you
34 all of F<inttypes.h> in addition to the ECB symbols.
35
36 There are currently no object files to link to - future versions might
37 come with an (optional) object code library to link against, to reduce
38 code size or gain access to additional features.
39
40 It also currently includes everything from F<inttypes.h>.
41
42 =head2 ABOUT THIS MANUAL / CONVENTIONS
43
44 This manual mainly describes each (public) function available after
45 including the F<ecb.h> header. The header might define other symbols than
46 these, but these are not part of the public API, and not supported in any
47 way.
48
49 When the manual mentions a "function" then this could be defined either as
50 as inline function, a macro, or an external symbol.
51
52 When functions use a concrete standard type, such as C<int> or
53 C<uint32_t>, then the corresponding function works only with that type. If
54 only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
55 the corresponding function relies on C to implement the correct types, and
56 is usually implemented as a macro. Specifically, a "bool" in this manual
57 refers to any kind of boolean value, not a specific type.
58
59 =head2 TYPES / TYPE SUPPORT
60
61 ecb.h makes sure that the following types are defined (in the expected way):
62
63 int8_t uint8_
64 int16_t uint16_t
65 int32_t uint32_
66 int64_t uint64_t
67 int_fast8_t uint_fast8_t
68 int_fast16_t uint_fast16_t
69 int_fast32_t uint_fast32_t
70 int_fast64_t uint_fast64_t
71 intptr_t uintptr_t
72
73 The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
74 platform (currently C<4> or C<8>) and can be used in preprocessor
75 expressions.
76
77 For C<ptrdiff_t> and C<size_t> use C<stddef.h>/C<cstddef>.
78
79 =head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
80
81 All the following symbols expand to an expression that can be tested in
82 preprocessor instructions as well as treated as a boolean (use C<!!> to
83 ensure it's either C<0> or C<1> if you need that).
84
85 =over 4
86
87 =item ECB_C
88
89 True if the implementation defines the C<__STDC__> macro to a true value,
90 while not claiming to be C++, i..e C, but not C++.
91
92 =item ECB_C99
93
94 True if the implementation claims to be compliant to C99 (ISO/IEC
95 9899:1999) or any later version, while not claiming to be C++.
96
97 Note that later versions (ECB_C11) remove core features again (for
98 example, variable length arrays).
99
100 =item ECB_C11, ECB_C17
101
102 True if the implementation claims to be compliant to C11/C17 (ISO/IEC
103 9899:2011, :20187) or any later version, while not claiming to be C++.
104
105 =item ECB_CPP
106
107 True if the implementation defines the C<__cplusplus__> macro to a true
108 value, which is typically true for C++ compilers.
109
110 =item ECB_CPP11, ECB_CPP14, ECB_CPP17
111
112 True if the implementation claims to be compliant to C++11/C++14/C++17
113 (ISO/IEC 14882:2011, :2014, :2017) or any later version.
114
115 Note that many C++20 features will likely have their own feature test
116 macros (see e.g. L<http://eel.is/c++draft/cpp.predefined#1.8>).
117
118 =item ECB_OPTIMIZE_SIZE
119
120 Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
121 can also be defined before including F<ecb.h>, in which case it will be
122 unchanged.
123
124 =item ECB_GCC_VERSION (major, minor)
125
126 Expands to a true value (suitable for testing by the preprocessor) if the
127 compiler used is GNU C and the version is the given version, or higher.
128
129 This macro tries to return false on compilers that claim to be GCC
130 compatible but aren't.
131
132 =item ECB_EXTERN_C
133
134 Expands to C<extern "C"> in C++, and a simple C<extern> in C.
135
136 This can be used to declare a single external C function:
137
138 ECB_EXTERN_C int printf (const char *format, ...);
139
140 =item ECB_EXTERN_C_BEG / ECB_EXTERN_C_END
141
142 These two macros can be used to wrap multiple C<extern "C"> definitions -
143 they expand to nothing in C.
144
145 They are most useful in header files:
146
147 ECB_EXTERN_C_BEG
148
149 int mycfun1 (int x);
150 int mycfun2 (int x);
151
152 ECB_EXTERN_C_END
153
154 =item ECB_STDFP
155
156 If this evaluates to a true value (suitable for testing by the
157 preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
158 and double/binary64 representations internally I<and> the endianness of
159 both types match the endianness of C<uint32_t> and C<uint64_t>.
160
161 This means you can just copy the bits of a C<float> (or C<double>) to an
162 C<uint32_t> (or C<uint64_t>) and get the raw IEEE 754 bit representation
163 without having to think about format or endianness.
164
165 This is true for basically all modern platforms, although F<ecb.h> might
166 not be able to deduce this correctly everywhere and might err on the safe
167 side.
168
169 =item ECB_AMD64, ECB_AMD64_X32
170
171 These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32
172 ABI, respectively, and undefined elsewhere.
173
174 The designers of the new X32 ABI for some inexplicable reason decided to
175 make it look exactly like amd64, even though it's completely incompatible
176 to that ABI, breaking about every piece of software that assumed that
177 C<__x86_64> stands for, well, the x86-64 ABI, making these macros
178 necessary.
179
180 =back
181
182 =head2 MACRO TRICKERY
183
184 =over 4
185
186 =item ECB_CONCAT (a, b)
187
188 Expands any macros in C<a> and C<b>, then concatenates the result to form
189 a single token. This is mainly useful to form identifiers from components,
190 e.g.:
191
192 #define S1 str
193 #define S2 cpy
194
195 ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
196
197 =item ECB_STRINGIFY (arg)
198
199 Expands any macros in C<arg> and returns the stringified version of
200 it. This is mainly useful to get the contents of a macro in string form,
201 e.g.:
202
203 #define SQL_LIMIT 100
204 sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
205
206 =item ECB_STRINGIFY_EXPR (expr)
207
208 Like C<ECB_STRINGIFY>, but additionally evaluates C<expr> to make sure it
209 is a valid expression. This is useful to catch typos or cases where the
210 macro isn't available:
211
212 #include <errno.h>
213
214 ECB_STRINGIFY (EDOM); // "33" (on my system at least)
215 ECB_STRINGIFY_EXPR (EDOM); // "33"
216
217 // now imagine we had a typo:
218
219 ECB_STRINGIFY (EDAM); // "EDAM"
220 ECB_STRINGIFY_EXPR (EDAM); // error: EDAM undefined
221
222 =back
223
224 =head2 ATTRIBUTES
225
226 A major part of libecb deals with additional attributes that can be
227 assigned to functions, variables and sometimes even types - much like
228 C<const> or C<volatile> in C. They are implemented using either GCC
229 attributes or other compiler/language specific features. Attributes
230 declarations must be put before the whole declaration:
231
232 ecb_const int mysqrt (int a);
233 ecb_unused int i;
234
235 =over 4
236
237 =item ecb_unused
238
239 Marks a function or a variable as "unused", which simply suppresses a
240 warning by the compiler when it detects it as unused. This is useful when
241 you e.g. declare a variable but do not always use it:
242
243 {
244 ecb_unused int var;
245
246 #ifdef SOMECONDITION
247 var = ...;
248 return var;
249 #else
250 return 0;
251 #endif
252 }
253
254 =item ecb_deprecated
255
256 Similar to C<ecb_unused>, but marks a function, variable or type as
257 deprecated. This makes some compilers warn when the type is used.
258
259 =item ecb_deprecated_message (message)
260
261 Same as C<ecb_deprecated>, but if possible, the specified diagnostic is
262 used instead of a generic depreciation message when the object is being
263 used.
264
265 =item ecb_inline
266
267 Expands either to (a compiler-specific equivalent of) C<static inline> or
268 to just C<static>, if inline isn't supported. It should be used to declare
269 functions that should be inlined, for code size or speed reasons.
270
271 Example: inline this function, it surely will reduce codesize.
272
273 ecb_inline int
274 negmul (int a, int b)
275 {
276 return - (a * b);
277 }
278
279 =item ecb_noinline
280
281 Prevents a function from being inlined - it might be optimised away, but
282 not inlined into other functions. This is useful if you know your function
283 is rarely called and large enough for inlining not to be helpful.
284
285 =item ecb_noreturn
286
287 Marks a function as "not returning, ever". Some typical functions that
288 don't return are C<exit> or C<abort> (which really works hard to not
289 return), and now you can make your own:
290
291 ecb_noreturn void
292 my_abort (const char *errline)
293 {
294 puts (errline);
295 abort ();
296 }
297
298 In this case, the compiler would probably be smart enough to deduce it on
299 its own, so this is mainly useful for declarations.
300
301 =item ecb_restrict
302
303 Expands to the C<restrict> keyword or equivalent on compilers that support
304 them, and to nothing on others. Must be specified on a pointer type or
305 an array index to indicate that the memory doesn't alias with any other
306 restricted pointer in the same scope.
307
308 Example: multiply a vector, and allow the compiler to parallelise the
309 loop, because it knows it doesn't overwrite input values.
310
311 void
312 multiply (ecb_restrict float *src,
313 ecb_restrict float *dst,
314 int len, float factor)
315 {
316 int i;
317
318 for (i = 0; i < len; ++i)
319 dst [i] = src [i] * factor;
320 }
321
322 =item ecb_const
323
324 Declares that the function only depends on the values of its arguments,
325 much like a mathematical function. It specifically does not read or write
326 any memory any arguments might point to, global variables, or call any
327 non-const functions. It also must not have any side effects.
328
329 Such a function can be optimised much more aggressively by the compiler -
330 for example, multiple calls with the same arguments can be optimised into
331 a single call, which wouldn't be possible if the compiler would have to
332 expect any side effects.
333
334 It is best suited for functions in the sense of mathematical functions,
335 such as a function returning the square root of its input argument.
336
337 Not suited would be a function that calculates the hash of some memory
338 area you pass in, prints some messages or looks at a global variable to
339 decide on rounding.
340
341 See C<ecb_pure> for a slightly less restrictive class of functions.
342
343 =item ecb_pure
344
345 Similar to C<ecb_const>, declares a function that has no side
346 effects. Unlike C<ecb_const>, the function is allowed to examine global
347 variables and any other memory areas (such as the ones passed to it via
348 pointers).
349
350 While these functions cannot be optimised as aggressively as C<ecb_const>
351 functions, they can still be optimised away in many occasions, and the
352 compiler has more freedom in moving calls to them around.
353
354 Typical examples for such functions would be C<strlen> or C<memcmp>. A
355 function that calculates the MD5 sum of some input and updates some MD5
356 state passed as argument would I<NOT> be pure, however, as it would modify
357 some memory area that is not the return value.
358
359 =item ecb_hot
360
361 This declares a function as "hot" with regards to the cache - the function
362 is used so often, that it is very beneficial to keep it in the cache if
363 possible.
364
365 The compiler reacts by trying to place hot functions near to each other in
366 memory.
367
368 Whether a function is hot or not often depends on the whole program,
369 and less on the function itself. C<ecb_cold> is likely more useful in
370 practise.
371
372 =item ecb_cold
373
374 The opposite of C<ecb_hot> - declares a function as "cold" with regards to
375 the cache, or in other words, this function is not called often, or not at
376 speed-critical times, and keeping it in the cache might be a waste of said
377 cache.
378
379 In addition to placing cold functions together (or at least away from hot
380 functions), this knowledge can be used in other ways, for example, the
381 function will be optimised for size, as opposed to speed, and codepaths
382 leading to calls to those functions can automatically be marked as if
383 C<ecb_expect_false> had been used to reach them.
384
385 Good examples for such functions would be error reporting functions, or
386 functions only called in exceptional or rare cases.
387
388 =item ecb_artificial
389
390 Declares the function as "artificial", in this case meaning that this
391 function is not really meant to be a function, but more like an accessor
392 - many methods in C++ classes are mere accessor functions, and having a
393 crash reported in such a method, or single-stepping through them, is not
394 usually so helpful, especially when it's inlined to just a few instructions.
395
396 Marking them as artificial will instruct the debugger about just this,
397 leading to happier debugging and thus happier lives.
398
399 Example: in some kind of smart-pointer class, mark the pointer accessor as
400 artificial, so that the whole class acts more like a pointer and less like
401 some C++ abstraction monster.
402
403 template<typename T>
404 struct my_smart_ptr
405 {
406 T *value;
407
408 ecb_artificial
409 operator T *()
410 {
411 return value;
412 }
413 };
414
415 =back
416
417 =head2 OPTIMISATION HINTS
418
419 =over 4
420
421 =item bool ecb_is_constant (expr)
422
423 Returns true iff the expression can be deduced to be a compile-time
424 constant, and false otherwise.
425
426 For example, when you have a C<rndm16> function that returns a 16 bit
427 random number, and you have a function that maps this to a range from
428 0..n-1, then you could use this inline function in a header file:
429
430 ecb_inline uint32_t
431 rndm (uint32_t n)
432 {
433 return (n * (uint32_t)rndm16 ()) >> 16;
434 }
435
436 However, for powers of two, you could use a normal mask, but that is only
437 worth it if, at compile time, you can detect this case. This is the case
438 when the passed number is a constant and also a power of two (C<n & (n -
439 1) == 0>):
440
441 ecb_inline uint32_t
442 rndm (uint32_t n)
443 {
444 return is_constant (n) && !(n & (n - 1))
445 ? rndm16 () & (num - 1)
446 : (n * (uint32_t)rndm16 ()) >> 16;
447 }
448
449 =item ecb_expect (expr, value)
450
451 Evaluates C<expr> and returns it. In addition, it tells the compiler that
452 the C<expr> evaluates to C<value> a lot, which can be used for static
453 branch optimisations.
454
455 Usually, you want to use the more intuitive C<ecb_expect_true> and
456 C<ecb_expect_false> functions instead.
457
458 =item bool ecb_expect_true (cond)
459
460 =item bool ecb_expect_false (cond)
461
462 These two functions expect a expression that is true or false and return
463 C<1> or C<0>, respectively, so when used in the condition of an C<if> or
464 other conditional statement, it will not change the program:
465
466 /* these two do the same thing */
467 if (some_condition) ...;
468 if (ecb_expect_true (some_condition)) ...;
469
470 However, by using C<ecb_expect_true>, you tell the compiler that the
471 condition is likely to be true (and for C<ecb_expect_false>, that it is
472 unlikely to be true).
473
474 For example, when you check for a null pointer and expect this to be a
475 rare, exceptional, case, then use C<ecb_expect_false>:
476
477 void my_free (void *ptr)
478 {
479 if (ecb_expect_false (ptr == 0))
480 return;
481 }
482
483 Consequent use of these functions to mark away exceptional cases or to
484 tell the compiler what the hot path through a function is can increase
485 performance considerably.
486
487 You might know these functions under the name C<likely> and C<unlikely>
488 - while these are common aliases, we find that the expect name is easier
489 to understand when quickly skimming code. If you wish, you can use
490 C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
491 C<ecb_expect_false> - these are simply aliases.
492
493 A very good example is in a function that reserves more space for some
494 memory block (for example, inside an implementation of a string stream) -
495 each time something is added, you have to check for a buffer overrun, but
496 you expect that most checks will turn out to be false:
497
498 /* make sure we have "size" extra room in our buffer */
499 ecb_inline void
500 reserve (int size)
501 {
502 if (ecb_expect_false (current + size > end))
503 real_reserve_method (size); /* presumably noinline */
504 }
505
506 =item ecb_assume (cond)
507
508 Tries to tell the compiler that some condition is true, even if it's not
509 obvious. This is not a function, but a statement: it cannot be used in
510 another expression.
511
512 This can be used to teach the compiler about invariants or other
513 conditions that might improve code generation, but which are impossible to
514 deduce form the code itself.
515
516 For example, the example reservation function from the C<ecb_expect_false>
517 description could be written thus (only C<ecb_assume> was added):
518
519 ecb_inline void
520 reserve (int size)
521 {
522 if (ecb_expect_false (current + size > end))
523 real_reserve_method (size); /* presumably noinline */
524
525 ecb_assume (current + size <= end);
526 }
527
528 If you then call this function twice, like this:
529
530 reserve (10);
531 reserve (1);
532
533 Then the compiler I<might> be able to optimise out the second call
534 completely, as it knows that C<< current + 1 > end >> is false and the
535 call will never be executed.
536
537 =item ecb_unreachable ()
538
539 This function does nothing itself, except tell the compiler that it will
540 never be executed. Apart from suppressing a warning in some cases, this
541 function can be used to implement C<ecb_assume> or similar functionality.
542
543 =item ecb_prefetch (addr, rw, locality)
544
545 Tells the compiler to try to prefetch memory at the given C<addr>ess
546 for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
547 C<0> means that there will only be one access later, C<3> means that
548 the data will likely be accessed very often, and values in between mean
549 something... in between. The memory pointed to by the address does not
550 need to be accessible (it could be a null pointer for example), but C<rw>
551 and C<locality> must be compile-time constants.
552
553 This is a statement, not a function: you cannot use it as part of an
554 expression.
555
556 An obvious way to use this is to prefetch some data far away, in a big
557 array you loop over. This prefetches memory some 128 array elements later,
558 in the hope that it will be ready when the CPU arrives at that location.
559
560 int sum = 0;
561
562 for (i = 0; i < N; ++i)
563 {
564 sum += arr [i]
565 ecb_prefetch (arr + i + 128, 0, 0);
566 }
567
568 It's hard to predict how far to prefetch, and most CPUs that can prefetch
569 are often good enough to predict this kind of behaviour themselves. It
570 gets more interesting with linked lists, especially when you do some fair
571 processing on each list element:
572
573 for (node *n = start; n; n = n->next)
574 {
575 ecb_prefetch (n->next, 0, 0);
576 ... do medium amount of work with *n
577 }
578
579 After processing the node, (part of) the next node might already be in
580 cache.
581
582 =back
583
584 =head2 BIT FIDDLING / BIT WIZARDRY
585
586 =over 4
587
588 =item bool ecb_big_endian ()
589
590 =item bool ecb_little_endian ()
591
592 These two functions return true if the byte order is big endian
593 (most-significant byte first) or little endian (least-significant byte
594 first) respectively.
595
596 On systems that are neither, their return values are unspecified.
597
598 =item int ecb_ctz32 (uint32_t x)
599
600 =item int ecb_ctz64 (uint64_t x)
601
602 =item int ecb_ctz (T x) [C++]
603
604 Returns the index of the least significant bit set in C<x> (or
605 equivalently the number of bits set to 0 before the least significant bit
606 set), starting from 0. If C<x> is 0 the result is undefined.
607
608 For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
609
610 The overloaded C++ C<ecb_ctz> function supports C<uint8_t>, C<uint16_t>,
611 C<uint32_t> and C<uint64_t> types.
612
613 For example:
614
615 ecb_ctz32 (3) = 0
616 ecb_ctz32 (6) = 1
617
618 =item bool ecb_is_pot32 (uint32_t x)
619
620 =item bool ecb_is_pot64 (uint32_t x)
621
622 =item bool ecb_is_pot (T x) [C++]
623
624 Returns true iff C<x> is a power of two or C<x == 0>.
625
626 For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
627
628 The overloaded C++ C<ecb_is_pot> function supports C<uint8_t>, C<uint16_t>,
629 C<uint32_t> and C<uint64_t> types.
630
631 =item int ecb_ld32 (uint32_t x)
632
633 =item int ecb_ld64 (uint64_t x)
634
635 =item int ecb_ld64 (T x) [C++]
636
637 Returns the index of the most significant bit set in C<x>, or the number
638 of digits the number requires in binary (so that C<< 2**ld <= x <
639 2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
640 to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
641 example to see how many bits a certain number requires to be encoded.
642
643 This function is similar to the "count leading zero bits" function, except
644 that that one returns how many zero bits are "in front" of the number (in
645 the given data type), while C<ecb_ld> returns how many bits the number
646 itself requires.
647
648 For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
649
650 The overloaded C++ C<ecb_ld> function supports C<uint8_t>, C<uint16_t>,
651 C<uint32_t> and C<uint64_t> types.
652
653 =item int ecb_popcount32 (uint32_t x)
654
655 =item int ecb_popcount64 (uint64_t x)
656
657 =item int ecb_popcount (T x) [C++]
658
659 Returns the number of bits set to 1 in C<x>.
660
661 For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
662
663 The overloaded C++ C<ecb_popcount> function supports C<uint8_t>, C<uint16_t>,
664 C<uint32_t> and C<uint64_t> types.
665
666 For example:
667
668 ecb_popcount32 (7) = 3
669 ecb_popcount32 (255) = 8
670
671 =item uint8_t ecb_bitrev8 (uint8_t x)
672
673 =item uint16_t ecb_bitrev16 (uint16_t x)
674
675 =item uint32_t ecb_bitrev32 (uint32_t x)
676
677 =item T ecb_bitrev (T x) [C++]
678
679 Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
680 and so on.
681
682 The overloaded C++ C<ecb_bitrev> function supports C<uint8_t>, C<uint16_t> and C<uint32_t> types.
683
684 Example:
685
686 ecb_bitrev8 (0xa7) = 0xea
687 ecb_bitrev32 (0xffcc4411) = 0x882233ff
688
689 =item T ecb_bitrev (T x) [C++]
690
691 Overloaded C++ bitrev function.
692
693 C<T> must be one of C<uint8_t>, C<uint16_t> or C<uint32_t>.
694
695 =item uint32_t ecb_bswap16 (uint32_t x)
696
697 =item uint32_t ecb_bswap32 (uint32_t x)
698
699 =item uint64_t ecb_bswap64 (uint64_t x)
700
701 =item T ecb_bswap (T x)
702
703 These functions return the value of the 16-bit (32-bit, 64-bit) value
704 C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
705 C<ecb_bswap32>).
706
707 The overloaded C++ C<ecb_bswap> function supports C<uint8_t>, C<uint16_t>,
708 C<uint32_t> and C<uint64_t> types.
709
710 =item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
711
712 =item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
713
714 =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
715
716 =item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
717
718 =item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
719
720 =item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
721
722 =item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
723
724 =item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
725
726 These two families of functions return the value of C<x> after rotating
727 all the bits by C<count> positions to the right (C<ecb_rotr>) or left
728 (C<ecb_rotl>).
729
730 Current GCC/clang versions understand these functions and usually compile
731 them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
732 on x86).
733
734 =item T ecb_rotl (T x, unsigned int count) [C++]
735
736 =item T ecb_rotr (T x, unsigned int count) [C++]
737
738 Overloaded C++ rotl/rotr functions.
739
740 C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
741
742 =back
743
744 =head2 HOST ENDIANNESS CONVERSION
745
746 =over 4
747
748 =item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
749
750 =item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
751
752 =item uint_fast64_t ecb_be_u64_to_host (uint_fast64_t v)
753
754 =item uint_fast16_t ecb_le_u16_to_host (uint_fast16_t v)
755
756 =item uint_fast32_t ecb_le_u32_to_host (uint_fast32_t v)
757
758 =item uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
759
760 Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order.
761
762 The naming convention is C<ecb_>(C<be>|C<le>)C<_u>C<16|32|64>C<_to_host>,
763 where C<be> and C<le> stand for big endian and little endian, respectively.
764
765 =item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
766
767 =item uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
768
769 =item uint_fast64_t ecb_host_to_be_u64 (uint_fast64_t v)
770
771 =item uint_fast16_t ecb_host_to_le_u16 (uint_fast16_t v)
772
773 =item uint_fast32_t ecb_host_to_le_u32 (uint_fast32_t v)
774
775 =item uint_fast64_t ecb_host_to_le_u64 (uint_fast64_t v)
776
777 Like above, but converts I<from> host byte order to the specified
778 endianness.
779
780 =back
781
782 In C++ the following additional template functions are supported:
783
784 =over 4
785
786 =item T ecb_be_to_host (T v)
787
788 =item T ecb_le_to_host (T v)
789
790 =item T ecb_host_to_be (T v)
791
792 =item T ecb_host_to_le (T v)
793
794 =back
795
796 These functions work like their C counterparts, above, but use templates,
797 which make them useful in generic code.
798
799 C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
800 (so unlike their C counterparts, there is a version for C<uint8_t>, which
801 again can be useful in generic code).
802
803 =head2 UNALIGNED LOAD/STORE
804
805 These function load or store unaligned multi-byte values.
806
807 =over 4
808
809 =item uint_fast16_t ecb_peek_u16_u (const void *ptr)
810
811 =item uint_fast32_t ecb_peek_u32_u (const void *ptr)
812
813 =item uint_fast64_t ecb_peek_u64_u (const void *ptr)
814
815 These functions load an unaligned, unsigned 16, 32 or 64 bit value from
816 memory.
817
818 =item uint_fast16_t ecb_peek_be_u16_u (const void *ptr)
819
820 =item uint_fast32_t ecb_peek_be_u32_u (const void *ptr)
821
822 =item uint_fast64_t ecb_peek_be_u64_u (const void *ptr)
823
824 =item uint_fast16_t ecb_peek_le_u16_u (const void *ptr)
825
826 =item uint_fast32_t ecb_peek_le_u32_u (const void *ptr)
827
828 =item uint_fast64_t ecb_peek_le_u64_u (const void *ptr)
829
830 Like above, but additionally convert from big endian (C<be>) or little
831 endian (C<le>) byte order to host byte order while doing so.
832
833 =item ecb_poke_u16_u (void *ptr, uint16_t v)
834
835 =item ecb_poke_u32_u (void *ptr, uint32_t v)
836
837 =item ecb_poke_u64_u (void *ptr, uint64_t v)
838
839 These functions store an unaligned, unsigned 16, 32 or 64 bit value to
840 memory.
841
842 =item ecb_poke_be_u16_u (void *ptr, uint_fast16_t v)
843
844 =item ecb_poke_be_u32_u (void *ptr, uint_fast32_t v)
845
846 =item ecb_poke_be_u64_u (void *ptr, uint_fast64_t v)
847
848 =item ecb_poke_le_u16_u (void *ptr, uint_fast16_t v)
849
850 =item ecb_poke_le_u32_u (void *ptr, uint_fast32_t v)
851
852 =item ecb_poke_le_u64_u (void *ptr, uint_fast64_t v)
853
854 Like above, but additionally convert from host byte order to big endian
855 (C<be>) or little endian (C<le>) byte order while doing so.
856
857 =back
858
859 In C++ the following additional template functions are supported:
860
861 =over 4
862
863 =item T ecb_peek<T> (const void *ptr)
864
865 =item T ecb_peek_be<T> (const void *ptr)
866
867 =item T ecb_peek_le<T> (const void *ptr)
868
869 =item T ecb_peek_u<T> (const void *ptr)
870
871 =item T ecb_peek_be_u<T> (const void *ptr)
872
873 =item T ecb_peek_le_u<T> (const void *ptr)
874
875 Similarly to their C counterparts, these functions load an unsigned 8, 16,
876 32 or 64 bit value from memory, with optional conversion from big/little
877 endian.
878
879 Since the type cannot be deduced, it has to be specified explicitly, e.g.
880
881 uint_fast16_t v = ecb_peek<uint16_t> (ptr);
882
883 C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
884
885 Unlike their C counterparts, these functions support 8 bit quantities
886 (C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
887 all of which hopefully makes them more useful in generic code.
888
889 =item ecb_poke (void *ptr, T v)
890
891 =item ecb_poke_be (void *ptr, T v)
892
893 =item ecb_poke_le (void *ptr, T v)
894
895 =item ecb_poke_u (void *ptr, T v)
896
897 =item ecb_poke_be_u (void *ptr, T v)
898
899 =item ecb_poke_le_u (void *ptr, T v)
900
901 Again, similarly to their C counterparts, these functions store an
902 unsigned 8, 16, 32 or z64 bit value to memory, with optional conversion to
903 big/little endian.
904
905 C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
906
907 Unlike their C counterparts, these functions support 8 bit quantities
908 (C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
909 all of which hopefully makes them more useful in generic code.
910
911 =back
912
913 =head2 FLOATING POINT FIDDLING
914
915 =over 4
916
917 =item ECB_INFINITY [-UECB_NO_LIBM]
918
919 Evaluates to positive infinity if supported by the platform, otherwise to
920 a truly huge number.
921
922 =item ECB_NAN [-UECB_NO_LIBM]
923
924 Evaluates to a quiet NAN if supported by the platform, otherwise to
925 C<ECB_INFINITY>.
926
927 =item float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
928
929 Same as C<ldexpf>, but always available.
930
931 =item uint32_t ecb_float_to_binary16 (float x) [-UECB_NO_LIBM]
932
933 =item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
934
935 =item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
936
937 These functions each take an argument in the native C<float> or C<double>
938 type and return the IEEE 754 bit representation of it (binary16/half,
939 binary32/single or binary64/double precision).
940
941 The bit representation is just as IEEE 754 defines it, i.e. the sign bit
942 will be the most significant bit, followed by exponent and mantissa.
943
944 This function should work even when the native floating point format isn't
945 IEEE compliant, of course at a speed and code size penalty, and of course
946 also within reasonable limits (it tries to convert NaNs, infinities and
947 denormals, but will likely convert negative zero to positive zero).
948
949 On all modern platforms (where C<ECB_STDFP> is true), the compiler should
950 be able to optimise away this function completely.
951
952 These functions can be helpful when serialising floats to the network - you
953 can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
954
955 Another use for these functions is to manipulate floating point values
956 directly.
957
958 Silly example: toggle the sign bit of a float.
959
960 /* On gcc-4.7 on amd64, */
961 /* this results in a single add instruction to toggle the bit, and 4 extra */
962 /* instructions to move the float value to an integer register and back. */
963
964 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
965
966 =item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM]
967
968 =item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
969
970 =item double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
971
972 The reverse operation of the previous function - takes the bit
973 representation of an IEEE binary16, binary32 or binary64 number (half,
974 single or double precision) and converts it to the native C<float> or
975 C<double> format.
976
977 This function should work even when the native floating point format isn't
978 IEEE compliant, of course at a speed and code size penalty, and of course
979 also within reasonable limits (it tries to convert normals and denormals,
980 and might be lucky for infinities, and with extraordinary luck, also for
981 negative zero).
982
983 On all modern platforms (where C<ECB_STDFP> is true), the compiler should
984 be able to optimise away this function completely.
985
986 =item uint16_t ecb_binary32_to_binary16 (uint32_t x)
987
988 =item uint32_t ecb_binary16_to_binary32 (uint16_t x)
989
990 Convert a IEEE binary32/single precision to binary16/half format, and vice
991 versa, handling all details (round-to-nearest-even, subnormals, infinity
992 and NaNs) correctly.
993
994 These are functions are available under C<-DECB_NO_LIBM>, since
995 they do not rely on the platform floating point format. The
996 C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
997 usually what you want.
998
999 =back
1000
1001 =head2 ARITHMETIC
1002
1003 =over 4
1004
1005 =item x = ecb_mod (m, n)
1006
1007 Returns C<m> modulo C<n>, which is the same as the positive remainder
1008 of the division operation between C<m> and C<n>, using floored
1009 division. Unlike the C remainder operator C<%>, this function ensures that
1010 the return value is always positive and that the two numbers I<m> and
1011 I<m' = m + i * n> result in the same value modulo I<n> - in other words,
1012 C<ecb_mod> implements the mathematical modulo operation, which is missing
1013 in the language.
1014
1015 C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
1016 negatable, that is, both C<m> and C<-m> must be representable in its
1017 type (this typically excludes the minimum signed integer value, the same
1018 limitation as for C</> and C<%> in C).
1019
1020 Current GCC/clang versions compile this into an efficient branchless
1021 sequence on almost all CPUs.
1022
1023 For example, when you want to rotate forward through the members of an
1024 array for increasing C<m> (which might be negative), then you should use
1025 C<ecb_mod>, as the C<%> operator might give either negative results, or
1026 change direction for negative values:
1027
1028 for (m = -100; m <= 100; ++m)
1029 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
1030
1031 =item x = ecb_div_rd (val, div)
1032
1033 =item x = ecb_div_ru (val, div)
1034
1035 Returns C<val> divided by C<div> rounded down or up, respectively.
1036 C<val> and C<div> must have integer types and C<div> must be strictly
1037 positive. Note that these functions are implemented with macros in C
1038 and with function templates in C++.
1039
1040 =back
1041
1042 =head2 UTILITY
1043
1044 =over 4
1045
1046 =item element_count = ecb_array_length (name)
1047
1048 Returns the number of elements in the array C<name>. For example:
1049
1050 int primes[] = { 2, 3, 5, 7, 11 };
1051 int sum = 0;
1052
1053 for (i = 0; i < ecb_array_length (primes); i++)
1054 sum += primes [i];
1055
1056 =back
1057
1058 =head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
1059
1060 These symbols need to be defined before including F<ecb.h> the first time.
1061
1062 =over 4
1063
1064 =item ECB_NO_THREADS
1065
1066 If F<ecb.h> is never used from multiple threads, then this symbol can
1067 be defined, in which case memory fences (and similar constructs) are
1068 completely removed, leading to more efficient code and fewer dependencies.
1069
1070 Setting this symbol to a true value implies C<ECB_NO_SMP>.
1071
1072 =item ECB_NO_SMP
1073
1074 The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
1075 multiple threads, but never concurrently (e.g. if the system the program
1076 runs on has only a single CPU with a single core, no hyperthreading and so
1077 on), then this symbol can be defined, leading to more efficient code and
1078 fewer dependencies.
1079
1080 =item ECB_NO_LIBM
1081
1082 When defined to C<1>, do not export any functions that might introduce
1083 dependencies on the math library (usually called F<-lm>) - these are
1084 marked with [-UECB_NO_LIBM].
1085
1086 =back
1087
1088 =head1 UNDOCUMENTED FUNCTIONALITY
1089
1090 F<ecb.h> is full of undocumented functionality as well, some of which is
1091 intended to be internal-use only, some of which we forgot to document, and
1092 some of which we hide because we are not sure we will keep the interface
1093 stable.
1094
1095 While you are welcome to rummage around and use whatever you find useful
1096 (we can't stop you), keep in mind that we will change undocumented
1097 functionality in incompatible ways without thinking twice, while we are
1098 considerably more conservative with documented things.
1099
1100 =head1 AUTHORS
1101
1102 C<libecb> is designed and maintained by:
1103
1104 Emanuele Giaquinta <e.giaquinta@glauco.it>
1105 Marc Alexander Lehmann <schmorp@schmorp.de>
1106
1107