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

Comparing libecb/ecb.pod (file contents):
Revision 1.76 by root, Mon Jan 20 13:13:56 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++.
… …
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 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>).
117
118=item ECB_OPTIMIZE_SIZE
119
120Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
121can also be defined before including F<ecb.h>, in which case it will be
122unchanged.
123
115=item ECB_GCC_VERSION (major, minor) 124=item ECB_GCC_VERSION (major, minor)
116 125
117Expands to a true value (suitable for testing in by the preprocessor) 126Expands to a true value (suitable for testing by the preprocessor) if the
118if 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.
119higher.
120 128
121This 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
122compatible but aren't. 130compatible 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
148If this evaluates to a true value (suitable for testing in by the 156If this evaluates to a true value (suitable for testing by the
149preprocessor), then C<float> and C<double> use IEEE 754 single/binary32 157preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
150and double/binary64 representations internally I<and> the endianness of 158and double/binary64 representations internally I<and> the endianness of
151both 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>.
152 160
153This 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
… …
155without having to think about format or endianness. 163without having to think about format or endianness.
156 164
157This 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
158not 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
159side. 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.
160 176
161=item ECB_AMD64, ECB_AMD64_X32 177=item ECB_AMD64, ECB_AMD64_X32
162 178
163These 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
164ABI, respectively, and undefined elsewhere. 180ABI, respectively, and undefined elsewhere.
… …
227=over 4 243=over 4
228 244
229=item ecb_unused 245=item ecb_unused
230 246
231Marks a function or a variable as "unused", which simply suppresses a 247Marks a function or a variable as "unused", which simply suppresses a
232warning 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
233declare a variable but do not always use it: 249you e.g. declare a variable but do not always use it:
234 250
235 { 251 {
236 ecb_unused int var; 252 ecb_unused int var;
237 253
238 #ifdef SOMECONDITION 254 #ifdef SOMECONDITION
… …
408 424
409=head2 OPTIMISATION HINTS 425=head2 OPTIMISATION HINTS
410 426
411=over 4 427=over 4
412 428
413=item ECB_OPTIMIZE_SIZE
414
415Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
416can also be defined before including F<ecb.h>, in which case it will be
417unchanged.
418
419=item bool ecb_is_constant (expr) 429=item bool ecb_is_constant (expr)
420 430
421Returns true iff the expression can be deduced to be a compile-time 431Returns true iff the expression can be deduced to be a compile-time
422constant, and false otherwise. 432constant, and false otherwise.
423 433
… …
595 605
596=item int ecb_ctz32 (uint32_t x) 606=item int ecb_ctz32 (uint32_t x)
597 607
598=item int ecb_ctz64 (uint64_t x) 608=item int ecb_ctz64 (uint64_t x)
599 609
610=item int ecb_ctz (T x) [C++]
611
600Returns the index of the least significant bit set in C<x> (or 612Returns the index of the least significant bit set in C<x> (or
601equivalently the number of bits set to 0 before the least significant bit 613equivalently the number of bits set to 0 before the least significant bit
602set), starting from 0. If C<x> is 0 the result is undefined. 614set), starting from 0. If C<x> is 0 the result is undefined.
603 615
604For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>. 616For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
605 617
618The overloaded C++ C<ecb_ctz> function supports C<uint8_t>, C<uint16_t>,
619C<uint32_t> and C<uint64_t> types.
620
606For example: 621For example:
607 622
608 ecb_ctz32 (3) = 0 623 ecb_ctz32 (3) = 0
609 ecb_ctz32 (6) = 1 624 ecb_ctz32 (6) = 1
610 625
611=item bool ecb_is_pot32 (uint32_t x) 626=item bool ecb_is_pot32 (uint32_t x)
612 627
613=item bool ecb_is_pot64 (uint32_t x) 628=item bool ecb_is_pot64 (uint32_t x)
614 629
630=item bool ecb_is_pot (T x) [C++]
631
615Returns true iff C<x> is a power of two or C<x == 0>. 632Returns true iff C<x> is a power of two or C<x == 0>.
616 633
617For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>. 634For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
618 635
636The overloaded C++ C<ecb_is_pot> function supports C<uint8_t>, C<uint16_t>,
637C<uint32_t> and C<uint64_t> types.
638
619=item int ecb_ld32 (uint32_t x) 639=item int ecb_ld32 (uint32_t x)
620 640
621=item int ecb_ld64 (uint64_t x) 641=item int ecb_ld64 (uint64_t x)
642
643=item int ecb_ld64 (T x) [C++]
622 644
623Returns the index of the most significant bit set in C<x>, or the number 645Returns the index of the most significant bit set in C<x>, or the number
624of digits the number requires in binary (so that C<< 2**ld <= x < 646of digits the number requires in binary (so that C<< 2**ld <= x <
6252**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is 6472**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
626to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for 648to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
… …
631the given data type), while C<ecb_ld> returns how many bits the number 653the given data type), while C<ecb_ld> returns how many bits the number
632itself requires. 654itself requires.
633 655
634For smaller types than C<uint32_t> you can safely use C<ecb_ld32>. 656For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
635 657
658The overloaded C++ C<ecb_ld> function supports C<uint8_t>, C<uint16_t>,
659C<uint32_t> and C<uint64_t> types.
660
636=item int ecb_popcount32 (uint32_t x) 661=item int ecb_popcount32 (uint32_t x)
637 662
638=item int ecb_popcount64 (uint64_t x) 663=item int ecb_popcount64 (uint64_t x)
639 664
665=item int ecb_popcount (T x) [C++]
666
640Returns the number of bits set to 1 in C<x>. 667Returns the number of bits set to 1 in C<x>.
641 668
642For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>. 669For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
670
671The overloaded C++ C<ecb_popcount> function supports C<uint8_t>, C<uint16_t>,
672C<uint32_t> and C<uint64_t> types.
643 673
644For example: 674For example:
645 675
646 ecb_popcount32 (7) = 3 676 ecb_popcount32 (7) = 3
647 ecb_popcount32 (255) = 8 677 ecb_popcount32 (255) = 8
… …
650 680
651=item uint16_t ecb_bitrev16 (uint16_t x) 681=item uint16_t ecb_bitrev16 (uint16_t x)
652 682
653=item uint32_t ecb_bitrev32 (uint32_t x) 683=item uint32_t ecb_bitrev32 (uint32_t x)
654 684
685=item T ecb_bitrev (T x) [C++]
686
655Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1 687Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
656and so on. 688and so on.
657 689
690The overloaded C++ C<ecb_bitrev> function supports C<uint8_t>, C<uint16_t> and C<uint32_t> types.
691
658Example: 692Example:
659 693
660 ecb_bitrev8 (0xa7) = 0xea 694 ecb_bitrev8 (0xa7) = 0xea
661 ecb_bitrev32 (0xffcc4411) = 0x882233ff 695 ecb_bitrev32 (0xffcc4411) = 0x882233ff
662 696
697=item T ecb_bitrev (T x) [C++]
698
699Overloaded C++ bitrev function.
700
701C<T> must be one of C<uint8_t>, C<uint16_t> or C<uint32_t>.
702
663=item uint32_t ecb_bswap16 (uint32_t x) 703=item uint32_t ecb_bswap16 (uint32_t x)
664 704
665=item uint32_t ecb_bswap32 (uint32_t x) 705=item uint32_t ecb_bswap32 (uint32_t x)
666 706
667=item uint64_t ecb_bswap64 (uint64_t x) 707=item uint64_t ecb_bswap64 (uint64_t x)
708
709=item T ecb_bswap (T x)
668 710
669These functions return the value of the 16-bit (32-bit, 64-bit) value 711These functions return the value of the 16-bit (32-bit, 64-bit) value
670C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in 712C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
671C<ecb_bswap32>). 713C<ecb_bswap32>).
672 714
673=item T ecb_bswap (T x) [C++] 715The overloaded C++ C<ecb_bswap> function supports C<uint8_t>, C<uint16_t>,
674 716C<uint32_t> and C<uint64_t> types.
675For C++, an additional generic bswap function is provided. It supports
676C<uint8_t>, C<uint16_t>, C<uint32_t> and C<uint64_t>.
677 717
678=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count) 718=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
679 719
680=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count) 720=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
681 721
… …
693 733
694These 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
695all 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
696(C<ecb_rotl>). 736(C<ecb_rotl>).
697 737
698Current GCC versions understand these functions and usually compile them 738Current GCC/clang versions understand these functions and usually compile
699to "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>
700x86). 740on x86).
741
742=item T ecb_rotl (T x, unsigned int count) [C++]
743
744=item T ecb_rotr (T x, unsigned int count) [C++]
745
746Overloaded C++ rotl/rotr functions.
747
748C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
701 749
702=back 750=back
703 751
704=head2 HOST ENDIANNESS CONVERSION 752=head2 HOST ENDIANNESS CONVERSION
705 753
… …
718=item uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v) 766=item uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
719 767
720Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order. 768Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order.
721 769
722The naming convention is C<ecb_>(C<be>|C<le>)C<_u>C<16|32|64>C<_to_host>, 770The naming convention is C<ecb_>(C<be>|C<le>)C<_u>C<16|32|64>C<_to_host>,
723where be and le stand for big endian and little endian, respectively. 771where C<be> and C<le> stand for big endian and little endian, respectively.
724 772
725=item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v) 773=item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
726 774
727=item uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v) 775=item uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
728 776
… …
737Like above, but converts I<from> host byte order to the specified 785Like above, but converts I<from> host byte order to the specified
738endianness. 786endianness.
739 787
740=back 788=back
741 789
742In C++ the following additional functions are supported: 790In C++ the following additional template functions are supported:
743 791
744=over 4 792=over 4
745 793
746=item T ecb_be_to_host (T v) 794=item T ecb_be_to_host (T v)
747 795
… …
749 797
750=item T ecb_host_to_be (T v) 798=item T ecb_host_to_be (T v)
751 799
752=item T ecb_host_to_le (T v) 800=item T ecb_host_to_le (T v)
753 801
802=back
803
754These work like their C counterparts, above, but use templates for the 804These functions work like their C counterparts, above, but use templates,
755type, which make them useful in generic code. 805which make them useful in generic code.
756 806
757C<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>
758(so unlike their C counterparts, there is a version for C<uint8_t>, which 808(so unlike their C counterparts, there is a version for C<uint8_t>, which
759again can be useful in generic code). 809again can be useful in generic code).
760 810
… …
812Like above, but additionally convert from host byte order to big endian 862Like above, but additionally convert from host byte order to big endian
813(C<be>) or little endian (C<le>) byte order while doing so. 863(C<be>) or little endian (C<le>) byte order while doing so.
814 864
815=back 865=back
816 866
817In C++ the following additional functions are supported: 867In C++ the following additional template functions are supported:
818 868
819=over 4 869=over 4
820 870
821=item T ecb_peek (const void *ptr) 871=item T ecb_peek<T> (const void *ptr)
822 872
823=item T ecb_peek_be (const void *ptr) 873=item T ecb_peek_be<T> (const void *ptr)
824 874
825=item T ecb_peek_le (const void *ptr) 875=item T ecb_peek_le<T> (const void *ptr)
826 876
827=item T ecb_peek_u (const void *ptr) 877=item T ecb_peek_u<T> (const void *ptr)
828 878
829=item T ecb_peek_be_u (const void *ptr) 879=item T ecb_peek_be_u<T> (const void *ptr)
830 880
831=item T ecb_peek_le_u (const void *ptr) 881=item T ecb_peek_le_u<T> (const void *ptr)
832 882
833Similarly to their C counterparts, these functions load an unsigned 8, 16, 883Similarly to their C counterparts, these functions load an unsigned 8, 16,
83432 or 64 bit value from memory, with optional conversion from big/little 88432 or 64 bit value from memory, with optional conversion from big/little
835endian. 885endian.
836 886
837Since the type cannot be deduced, it has top be specified explicitly, e.g. 887Since the type cannot be deduced, it has to be specified explicitly, e.g.
838 888
839 uint_fast16_t v = ecb_peek<uint16_t> (ptr); 889 uint_fast16_t v = ecb_peek<uint16_t> (ptr);
840 890
841C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>. 891C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
842 892
… …
973C<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
974negatable, 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
975type (this typically excludes the minimum signed integer value, the same 1025type (this typically excludes the minimum signed integer value, the same
976limitation as for C</> and C<%> in C). 1026limitation as for C</> and C<%> in C).
977 1027
978Current GCC versions compile this into an efficient branchless sequence on 1028Current GCC/clang versions compile this into an efficient branchless
979almost all CPUs. 1029sequence on almost all CPUs.
980 1030
981For 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
982array 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
983C<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
984change direction for negative values: 1034change direction for negative values:

Diff Legend

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