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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.84 by root, Mon Jan 20 21:10:16 2020 UTC vs.
Revision 1.86 by root, Thu Apr 30 23:24:45 2020 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
… …
235=over 4 235=over 4
236 236
237=item ecb_unused 237=item ecb_unused
238 238
239Marks a function or a variable as "unused", which simply suppresses a 239Marks a function or a variable as "unused", which simply suppresses a
240warning by GCC when it detects it as unused. This is useful when you e.g. 240warning by the compiler when it detects it as unused. This is useful when
241declare a variable but do not always use it: 241you e.g. declare a variable but do not always use it:
242 242
243 { 243 {
244 ecb_unused int var; 244 ecb_unused int var;
245 245
246 #ifdef SOMECONDITION 246 #ifdef SOMECONDITION
… …
725 725
726These two families of functions return the value of C<x> after rotating 726These two families of functions return the value of C<x> after rotating
727all the bits by C<count> positions to the right (C<ecb_rotr>) or left 727all the bits by C<count> positions to the right (C<ecb_rotr>) or left
728(C<ecb_rotl>). 728(C<ecb_rotl>).
729 729
730Current GCC versions understand these functions and usually compile them 730Current GCC/clang versions understand these functions and usually compile
731to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 731them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
732x86). 732on x86).
733 733
734=item T ecb_rotl (T x, unsigned int count) [C++] 734=item T ecb_rotl (T x, unsigned int count) [C++]
735 735
736=item T ecb_rotr (T x, unsigned int count) [C++] 736=item T ecb_rotr (T x, unsigned int count) [C++]
737 737
… …
788=item T ecb_le_to_host (T v) 788=item T ecb_le_to_host (T v)
789 789
790=item T ecb_host_to_be (T v) 790=item T ecb_host_to_be (T v)
791 791
792=item T ecb_host_to_le (T v) 792=item T ecb_host_to_le (T v)
793
794=back
793 795
794These functions work like their C counterparts, above, but use templates, 796These functions work like their C counterparts, above, but use templates,
795which make them useful in generic code. 797which make them useful in generic code.
796 798
797C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t> 799C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
… …
1013C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be 1015C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
1014negatable, that is, both C<m> and C<-m> must be representable in its 1016negatable, that is, both C<m> and C<-m> must be representable in its
1015type (this typically excludes the minimum signed integer value, the same 1017type (this typically excludes the minimum signed integer value, the same
1016limitation as for C</> and C<%> in C). 1018limitation as for C</> and C<%> in C).
1017 1019
1018Current GCC versions compile this into an efficient branchless sequence on 1020Current GCC/clang versions compile this into an efficient branchless
1019almost all CPUs. 1021sequence on almost all CPUs.
1020 1022
1021For example, when you want to rotate forward through the members of an 1023For example, when you want to rotate forward through the members of an
1022array for increasing C<m> (which might be negative), then you should use 1024array for increasing C<m> (which might be negative), then you should use
1023C<ecb_mod>, as the C<%> operator might give either negative results, or 1025C<ecb_mod>, as the C<%> operator might give either negative results, or
1024change direction for negative values: 1026change direction for negative values:

Diff Legend

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