… | |
… | |
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++. |
… | |
… | |
109 | |
109 | |
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 | |
|
|
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>). |
114 | |
117 | |
115 | =item ECB_OPTIMIZE_SIZE |
118 | =item ECB_OPTIMIZE_SIZE |
116 | |
119 | |
117 | Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol |
120 | Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol |
118 | can also be defined before including F<ecb.h>, in which case it will be |
121 | can also be defined before including F<ecb.h>, in which case it will be |
119 | unchanged. |
122 | unchanged. |
120 | |
123 | |
121 | =item ECB_GCC_VERSION (major, minor) |
124 | =item ECB_GCC_VERSION (major, minor) |
122 | |
125 | |
123 | 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 |
124 | 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. |
125 | higher. |
|
|
126 | |
128 | |
127 | 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 |
128 | compatible but aren't. |
130 | compatible but aren't. |
129 | |
131 | |
130 | =item ECB_EXTERN_C |
132 | =item ECB_EXTERN_C |
… | |
… | |
149 | |
151 | |
150 | ECB_EXTERN_C_END |
152 | ECB_EXTERN_C_END |
151 | |
153 | |
152 | =item ECB_STDFP |
154 | =item ECB_STDFP |
153 | |
155 | |
154 | 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 |
155 | 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 |
156 | and double/binary64 representations internally I<and> the endianness of |
158 | and double/binary64 representations internally I<and> the endianness of |
157 | 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>. |
158 | |
160 | |
159 | 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 |
… | |
… | |
233 | =over 4 |
235 | =over 4 |
234 | |
236 | |
235 | =item ecb_unused |
237 | =item ecb_unused |
236 | |
238 | |
237 | 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 |
238 | 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 |
239 | declare a variable but do not always use it: |
241 | you e.g. declare a variable but do not always use it: |
240 | |
242 | |
241 | { |
243 | { |
242 | ecb_unused int var; |
244 | ecb_unused int var; |
243 | |
245 | |
244 | #ifdef SOMECONDITION |
246 | #ifdef SOMECONDITION |
… | |
… | |
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 | |
… | |
… | |
1011 | C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be |
1013 | 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 |
1014 | 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 |
1015 | type (this typically excludes the minimum signed integer value, the same |
1014 | limitation as for C</> and C<%> in C). |
1016 | limitation as for C</> and C<%> in C). |
1015 | |
1017 | |
1016 | Current GCC versions compile this into an efficient branchless sequence on |
1018 | Current GCC/clang versions compile this into an efficient branchless |
1017 | almost all CPUs. |
1019 | sequence on almost all CPUs. |
1018 | |
1020 | |
1019 | For example, when you want to rotate forward through the members of an |
1021 | 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 |
1022 | 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 |
1023 | C<ecb_mod>, as the C<%> operator might give either negative results, or |
1022 | change direction for negative values: |
1024 | change direction for negative values: |