… | |
… | |
10 | |
10 | |
11 | Its homepage can be found here: |
11 | Its homepage can be found here: |
12 | |
12 | |
13 | http://software.schmorp.de/pkg/libecb |
13 | http://software.schmorp.de/pkg/libecb |
14 | |
14 | |
15 | It mainly provides a number of wrappers around GCC built-ins, together |
15 | It mainly provides a number of wrappers around many compiler built-ins, |
16 | with replacement functions for other compilers. In addition to this, |
16 | together with replacement functions for other compilers. In addition |
17 | it provides a number of other lowlevel C utilities, such as endianness |
17 | to this, it provides a number of other lowlevel C utilities, such as |
18 | detection, byte swapping or bit rotations. |
18 | endianness detection, byte swapping or bit rotations. |
19 | |
19 | |
20 | Or in other words, things that should be built into any standard C system, |
20 | Or in other words, things that should be built into any standard C |
21 | but aren't, implemented as efficient as possible with GCC, and still |
21 | system, but aren't, implemented as efficient as possible with GCC (clang, |
22 | correct with other compilers. |
22 | msvc...), and still correct with other compilers. |
23 | |
23 | |
24 | More might come. |
24 | More might come. |
25 | |
25 | |
26 | =head2 ABOUT THE HEADER |
26 | =head2 ABOUT THE HEADER |
27 | |
27 | |
… | |
… | |
85 | =over 4 |
85 | =over 4 |
86 | |
86 | |
87 | =item ECB_C |
87 | =item ECB_C |
88 | |
88 | |
89 | True if the implementation defines the C<__STDC__> macro to a true value, |
89 | True if the implementation defines the C<__STDC__> macro to a true value, |
90 | while not claiming to be C++. |
90 | while not claiming to be C++, i..e C, but not C++. |
91 | |
91 | |
92 | =item ECB_C99 |
92 | =item ECB_C99 |
93 | |
93 | |
94 | True if the implementation claims to be compliant to C99 (ISO/IEC |
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++. |
95 | 9899:1999) or any later version, while not claiming to be C++. |
… | |
… | |
110 | =item ECB_CPP11, ECB_CPP14, ECB_CPP17 |
110 | =item ECB_CPP11, ECB_CPP14, ECB_CPP17 |
111 | |
111 | |
112 | True if the implementation claims to be compliant to C++11/C++14/C++17 |
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. |
113 | (ISO/IEC 14882:2011, :2014, :2017) or any later version. |
114 | |
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 | |
115 | =item ECB_GCC_VERSION (major, minor) |
124 | =item ECB_GCC_VERSION (major, minor) |
116 | |
125 | |
117 | Expands to a true value (suitable for testing in by the preprocessor) |
126 | Expands to a true value (suitable for testing by the preprocessor) if the |
118 | if the compiler used is GNU C and the version is the given version, or |
127 | compiler used is GNU C and the version is the given version, or higher. |
119 | higher. |
|
|
120 | |
128 | |
121 | This macro tries to return false on compilers that claim to be GCC |
129 | This macro tries to return false on compilers that claim to be GCC |
122 | compatible but aren't. |
130 | compatible but aren't. |
123 | |
131 | |
124 | =item ECB_EXTERN_C |
132 | =item ECB_EXTERN_C |
… | |
… | |
143 | |
151 | |
144 | ECB_EXTERN_C_END |
152 | ECB_EXTERN_C_END |
145 | |
153 | |
146 | =item ECB_STDFP |
154 | =item ECB_STDFP |
147 | |
155 | |
148 | If this evaluates to a true value (suitable for testing in by the |
156 | If this evaluates to a true value (suitable for testing by the |
149 | preprocessor), then C<float> and C<double> use IEEE 754 single/binary32 |
157 | preprocessor), then C<float> and C<double> use IEEE 754 single/binary32 |
150 | and double/binary64 representations internally I<and> the endianness of |
158 | and double/binary64 representations internally I<and> the endianness of |
151 | both types match the endianness of C<uint32_t> and C<uint64_t>. |
159 | both types match the endianness of C<uint32_t> and C<uint64_t>. |
152 | |
160 | |
153 | This means you can just copy the bits of a C<float> (or C<double>) to an |
161 | This means you can just copy the bits of a C<float> (or C<double>) to an |
… | |
… | |
227 | =over 4 |
235 | =over 4 |
228 | |
236 | |
229 | =item ecb_unused |
237 | =item ecb_unused |
230 | |
238 | |
231 | Marks a function or a variable as "unused", which simply suppresses a |
239 | Marks a function or a variable as "unused", which simply suppresses a |
232 | warning by GCC when it detects it as unused. This is useful when you e.g. |
240 | warning by the compiler when it detects it as unused. This is useful when |
233 | declare a variable but do not always use it: |
241 | you e.g. declare a variable but do not always use it: |
234 | |
242 | |
235 | { |
243 | { |
236 | ecb_unused int var; |
244 | ecb_unused int var; |
237 | |
245 | |
238 | #ifdef SOMECONDITION |
246 | #ifdef SOMECONDITION |
… | |
… | |
408 | |
416 | |
409 | =head2 OPTIMISATION HINTS |
417 | =head2 OPTIMISATION HINTS |
410 | |
418 | |
411 | =over 4 |
419 | =over 4 |
412 | |
420 | |
413 | =item ECB_OPTIMIZE_SIZE |
|
|
414 | |
|
|
415 | Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol |
|
|
416 | can also be defined before including F<ecb.h>, in which case it will be |
|
|
417 | unchanged. |
|
|
418 | |
|
|
419 | =item bool ecb_is_constant (expr) |
421 | =item bool ecb_is_constant (expr) |
420 | |
422 | |
421 | Returns true iff the expression can be deduced to be a compile-time |
423 | Returns true iff the expression can be deduced to be a compile-time |
422 | constant, and false otherwise. |
424 | constant, and false otherwise. |
423 | |
425 | |
… | |
… | |
723 | |
725 | |
724 | These two families of functions return the value of C<x> after rotating |
726 | These two families of functions return the value of C<x> after rotating |
725 | all the bits by C<count> positions to the right (C<ecb_rotr>) or left |
727 | all the bits by C<count> positions to the right (C<ecb_rotr>) or left |
726 | (C<ecb_rotl>). |
728 | (C<ecb_rotl>). |
727 | |
729 | |
728 | Current GCC versions understand these functions and usually compile them |
730 | Current GCC/clang versions understand these functions and usually compile |
729 | to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on |
731 | them to "optimal" code (e.g. a single C<rol> or a combination of C<shld> |
730 | x86). |
732 | on x86). |
731 | |
733 | |
732 | =item T ecb_rotl (T x, unsigned int count) [C++] |
734 | =item T ecb_rotl (T x, unsigned int count) [C++] |
733 | |
735 | |
734 | =item T ecb_rotr (T x, unsigned int count) [C++] |
736 | =item T ecb_rotr (T x, unsigned int count) [C++] |
735 | |
737 | |
… | |
… | |
786 | =item T ecb_le_to_host (T v) |
788 | =item T ecb_le_to_host (T v) |
787 | |
789 | |
788 | =item T ecb_host_to_be (T v) |
790 | =item T ecb_host_to_be (T v) |
789 | |
791 | |
790 | =item T ecb_host_to_le (T v) |
792 | =item T ecb_host_to_le (T v) |
|
|
793 | |
|
|
794 | =back |
791 | |
795 | |
792 | These functions work like their C counterparts, above, but use templates, |
796 | These functions work like their C counterparts, above, but use templates, |
793 | which make them useful in generic code. |
797 | which make them useful in generic code. |
794 | |
798 | |
795 | C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t> |
799 | C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t> |
… | |
… | |
1011 | C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be |
1015 | C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be |
1012 | negatable, that is, both C<m> and C<-m> must be representable in its |
1016 | negatable, that is, both C<m> and C<-m> must be representable in its |
1013 | type (this typically excludes the minimum signed integer value, the same |
1017 | type (this typically excludes the minimum signed integer value, the same |
1014 | limitation as for C</> and C<%> in C). |
1018 | limitation as for C</> and C<%> in C). |
1015 | |
1019 | |
1016 | Current GCC versions compile this into an efficient branchless sequence on |
1020 | Current GCC/clang versions compile this into an efficient branchless |
1017 | almost all CPUs. |
1021 | sequence on almost all CPUs. |
1018 | |
1022 | |
1019 | For example, when you want to rotate forward through the members of an |
1023 | For example, when you want to rotate forward through the members of an |
1020 | array for increasing C<m> (which might be negative), then you should use |
1024 | array for increasing C<m> (which might be negative), then you should use |
1021 | C<ecb_mod>, as the C<%> operator might give either negative results, or |
1025 | C<ecb_mod>, as the C<%> operator might give either negative results, or |
1022 | change direction for negative values: |
1026 | change direction for negative values: |