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

Comparing libecb/ecb.pod (file contents):
Revision 1.81 by root, Mon Jan 20 21:01:29 2020 UTC vs.
Revision 1.87 by root, Mon Jun 21 21:26:48 2021 UTC

… …
10 10
11Its homepage can be found here: 11Its homepage can be found here:
12 12
13 http://software.schmorp.de/pkg/libecb 13 http://software.schmorp.de/pkg/libecb
14 14
15It mainly provides a number of wrappers around GCC built-ins, together 15It mainly provides a number of wrappers around many compiler built-ins,
16with replacement functions for other compilers. In addition to this, 16together with replacement functions for other compilers. In addition
17it provides a number of other lowlevel C utilities, such as endianness 17to this, it provides a number of other lowlevel C utilities, such as
18detection, byte swapping or bit rotations. 18endianness detection, byte swapping or bit rotations.
19 19
20Or in other words, things that should be built into any standard C system, 20Or in other words, things that should be built into any standard C
21but aren't, implemented as efficient as possible with GCC, and still 21system, but aren't, implemented as efficient as possible with GCC (clang,
22correct with other compilers. 22msvc...), and still correct with other compilers.
23 23
24More might come. 24More 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
89True if the implementation defines the C<__STDC__> macro to a true value, 89True if the implementation defines the C<__STDC__> macro to a true value,
90while not claiming to be C++. 90while not claiming to be C++, i..e C, but not C++.
91 91
92=item ECB_C99 92=item ECB_C99
93 93
94True if the implementation claims to be compliant to C99 (ISO/IEC 94True if the implementation claims to be compliant to C99 (ISO/IEC
959899:1999) or any later version, while not claiming to be C++. 959899: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
112True if the implementation claims to be compliant to C++11/C++14/C++17 112True 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
115Note that many C++20 features will likely have their own feature test
116macros (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
117Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol 120Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
118can also be defined before including F<ecb.h>, in which case it will be 121can also be defined before including F<ecb.h>, in which case it will be
119unchanged. 122unchanged.
120 123
121=item ECB_GCC_VERSION (major, minor) 124=item ECB_GCC_VERSION (major, minor)
122 125
123Expands to a true value (suitable for testing in by the preprocessor) 126Expands to a true value (suitable for testing by the preprocessor) if the
124if the compiler used is GNU C and the version is the given version, or 127compiler used is GNU C and the version is the given version, or higher.
125higher.
126 128
127This macro tries to return false on compilers that claim to be GCC 129This macro tries to return false on compilers that claim to be GCC
128compatible but aren't. 130compatible 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
154If this evaluates to a true value (suitable for testing in by the 156If this evaluates to a true value (suitable for testing by the
155preprocessor), then C<float> and C<double> use IEEE 754 single/binary32 157preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
156and double/binary64 representations internally I<and> the endianness of 158and double/binary64 representations internally I<and> the endianness of
157both types match the endianness of C<uint32_t> and C<uint64_t>. 159both types match the endianness of C<uint32_t> and C<uint64_t>.
158 160
159This means you can just copy the bits of a C<float> (or C<double>) to an 161This means you can just copy the bits of a C<float> (or C<double>) to an
… …
161without having to think about format or endianness. 163without having to think about format or endianness.
162 164
163This is true for basically all modern platforms, although F<ecb.h> might 165This is true for basically all modern platforms, although F<ecb.h> might
164not be able to deduce this correctly everywhere and might err on the safe 166not be able to deduce this correctly everywhere and might err on the safe
165side. 167side.
168
169=item ECB_64BIT_NATIVE
170
171Evaluates to a true value (suitable for both preprocessor and C code
172testing) if 64 bit integer types on this architecture are evaluated
173"natively", that is, with similar speeds as 32 bit integerss. While 64 bit
174integer support is very common (and in fatc required by libecb), 32 bit
175cpus have to emulate operations on them, so you might want to avoid them.
166 176
167=item ECB_AMD64, ECB_AMD64_X32 177=item ECB_AMD64, ECB_AMD64_X32
168 178
169These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32 179These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32
170ABI, respectively, and undefined elsewhere. 180ABI, respectively, and undefined elsewhere.
… …
233=over 4 243=over 4
234 244
235=item ecb_unused 245=item ecb_unused
236 246
237Marks a function or a variable as "unused", which simply suppresses a 247Marks a function or a variable as "unused", which simply suppresses a
238warning by GCC when it detects it as unused. This is useful when you e.g. 248warning by the compiler when it detects it as unused. This is useful when
239declare a variable but do not always use it: 249you e.g. declare a variable but do not always use it:
240 250
241 { 251 {
242 ecb_unused int var; 252 ecb_unused int var;
243 253
244 #ifdef SOMECONDITION 254 #ifdef SOMECONDITION
… …
723 733
724These two families of functions return the value of C<x> after rotating 734These two families of functions return the value of C<x> after rotating
725all the bits by C<count> positions to the right (C<ecb_rotr>) or left 735all the bits by C<count> positions to the right (C<ecb_rotr>) or left
726(C<ecb_rotl>). 736(C<ecb_rotl>).
727 737
728Current GCC versions understand these functions and usually compile them 738Current GCC/clang versions understand these functions and usually compile
729to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 739them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
730x86). 740on x86).
731 741
732=item T ecb_rotl (T x, unsigned int count) [C++] 742=item T ecb_rotl (T x, unsigned int count) [C++]
733 743
734=item T ecb_rotr (T x, unsigned int count) [C++] 744=item T ecb_rotr (T x, unsigned int count) [C++]
735 745
… …
786=item T ecb_le_to_host (T v) 796=item T ecb_le_to_host (T v)
787 797
788=item T ecb_host_to_be (T v) 798=item T ecb_host_to_be (T v)
789 799
790=item T ecb_host_to_le (T v) 800=item T ecb_host_to_le (T v)
801
802=back
791 803
792These functions work like their C counterparts, above, but use templates, 804These functions work like their C counterparts, above, but use templates,
793which make them useful in generic code. 805which make them useful in generic code.
794 806
795C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t> 807C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
… …
1011C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be 1023C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
1012negatable, that is, both C<m> and C<-m> must be representable in its 1024negatable, that is, both C<m> and C<-m> must be representable in its
1013type (this typically excludes the minimum signed integer value, the same 1025type (this typically excludes the minimum signed integer value, the same
1014limitation as for C</> and C<%> in C). 1026limitation as for C</> and C<%> in C).
1015 1027
1016Current GCC versions compile this into an efficient branchless sequence on 1028Current GCC/clang versions compile this into an efficient branchless
1017almost all CPUs. 1029sequence on almost all CPUs.
1018 1030
1019For example, when you want to rotate forward through the members of an 1031For example, when you want to rotate forward through the members of an
1020array for increasing C<m> (which might be negative), then you should use 1032array for increasing C<m> (which might be negative), then you should use
1021C<ecb_mod>, as the C<%> operator might give either negative results, or 1033C<ecb_mod>, as the C<%> operator might give either negative results, or
1022change direction for negative values: 1034change direction for negative values:

Diff Legend

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