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

Comparing libecb/ecb.pod (file contents):
Revision 1.18 by root, Fri May 27 00:01:28 2011 UTC vs.
Revision 1.24 by root, Tue May 31 21:10:37 2011 UTC

… …
15It mainly provides a number of wrappers around GCC built-ins, together 15It mainly provides a number of wrappers around GCC built-ins, together
16with replacement functions for other compilers. In addition to this, 16with replacement functions for other compilers. In addition to this,
17it provides a number of other lowlevel C utilities, such as endianness 17it provides a number of other lowlevel C utilities, such as endianness
18detection, byte swapping or bit rotations. 18detection, byte swapping or bit rotations.
19 19
20Or in other words, things that should be built-in into any standard C 20Or in other words, things that should be built into any standard C system,
21system, but aren't. 21but aren't, implemented as efficient as possible with GCC, and still
22correct with other compilers.
22 23
23More might come. 24More might come.
24 25
25=head2 ABOUT THE HEADER 26=head2 ABOUT THE HEADER
26 27
… …
55is usually implemented as a macro. Specifically, a "bool" in this manual 56is usually implemented as a macro. Specifically, a "bool" in this manual
56refers to any kind of boolean value, not a specific type. 57refers to any kind of boolean value, not a specific type.
57 58
58=head2 GCC ATTRIBUTES 59=head2 GCC ATTRIBUTES
59 60
60blabla where to put, what others 61A major part of libecb deals with GCC attributes. These are additional
62attributes that you cna assign to functions, variables and sometimes even
63types - much like C<const> or C<volatile> in C.
64
65While GCC allows declarations to show up in many surprising places,
66but not in many expeted places, the safest way is to put attribute
67declarations before the whole declaration:
68
69 ecb_const int mysqrt (int a);
70 ecb_unused int i;
71
72For variables, it is often nicer to put the attribute after the name, and
73avoid multiple declarations using commas:
74
75 int i ecb_unused;
61 76
62=over 4 77=over 4
63 78
64=item ecb_attribute ((attrs...)) 79=item ecb_attribute ((attrs...))
65 80
… …
105 { 120 {
106 puts (errline); 121 puts (errline);
107 abort (); 122 abort ();
108 } 123 }
109 124
110In this case, the compiler would probbaly be smart enough to decude it on 125In this case, the compiler would probably be smart enough to deduce it on
111it's own, so this is mainly useful for declarations. 126its own, so this is mainly useful for declarations.
112 127
113=item ecb_const 128=item ecb_const
114 129
115Declares that the function only depends on the values of it's arguments, 130Declares that the function only depends on the values of its arguments,
116much like a mathematical function. It specifically does not read or write 131much like a mathematical function. It specifically does not read or write
117any memory any arguments might point to, global variables, or call any 132any memory any arguments might point to, global variables, or call any
118non-const functions. It also must not have any side effects. 133non-const functions. It also must not have any side effects.
119 134
120Such a function can be optimised much more aggressively by the compiler - 135Such a function can be optimised much more aggressively by the compiler -
121for example, multiple calls with the same arguments can be optimised into 136for example, multiple calls with the same arguments can be optimised into
122a single call, which wouldn't be possible if the compiler would have to 137a single call, which wouldn't be possible if the compiler would have to
123expect any side effects. 138expect any side effects.
124 139
125It is best suited for functions in the sense of mathematical functions, 140It is best suited for functions in the sense of mathematical functions,
126such as a function return the square root of its input argument. 141such as a function returning the square root of its input argument.
127 142
128Not suited would be a function that calculates the hash of some memory 143Not suited would be a function that calculates the hash of some memory
129area you pass in, prints some messages or looks at a global variable to 144area you pass in, prints some messages or looks at a global variable to
130decide on rounding. 145decide on rounding.
131 146
… …
154possible. 169possible.
155 170
156The compiler reacts by trying to place hot functions near to each other in 171The compiler reacts by trying to place hot functions near to each other in
157memory. 172memory.
158 173
159Whether a function is hot or not often depend son the whole program, 174Whether a function is hot or not often depends on the whole program,
160and less on the function itself. C<ecb_cold> is likely more useful in 175and less on the function itself. C<ecb_cold> is likely more useful in
161practise. 176practise.
162 177
163=item ecb_cold 178=item ecb_cold
164 179
… …
169 184
170In addition to placing cold functions together (or at least away from hot 185In addition to placing cold functions together (or at least away from hot
171functions), this knowledge can be used in other ways, for example, the 186functions), this knowledge can be used in other ways, for example, the
172function will be optimised for size, as opposed to speed, and codepaths 187function will be optimised for size, as opposed to speed, and codepaths
173leading to calls to those functions can automatically be marked as if 188leading to calls to those functions can automatically be marked as if
174C<ecb_unlikel> had been used to reach them. 189C<ecb_unlikely> had been used to reach them.
175 190
176Good examples for such functions would be error reporting functions, or 191Good examples for such functions would be error reporting functions, or
177functions only called in exceptional or rare cases. 192functions only called in exceptional or rare cases.
178 193
179=item ecb_artificial 194=item ecb_artificial
… …
372 387
373These two functions return true if the byte order is big endian 388These two functions return true if the byte order is big endian
374(most-significant byte first) or little endian (least-significant byte 389(most-significant byte first) or little endian (least-significant byte
375first) respectively. 390first) respectively.
376 391
392On systems that are neither, their return values are unspecified.
393
377=item int ecb_ctz32 (uint32_t x) 394=item int ecb_ctz32 (uint32_t x)
378 395
379Returns the index of the least significant bit set in C<x> (or 396Returns the index of the least significant bit set in C<x> (or
380equivalently the number of bits set to 0 before the least significant 397equivalently the number of bits set to 0 before the least significant bit
381bit set), starting from 0. If C<x> is 0 the result is undefined. A 398set), starting from 0. If C<x> is 0 the result is undefined. A common use
382common use case is to compute the integer binary logarithm, i.e., 399case is to compute the integer binary logarithm, i.e., C<floor (log2
383floor(log2(n)). For example: 400(n))>. For example:
384 401
385 ecb_ctz32 (3) = 0 402 ecb_ctz32 (3) = 0
386 ecb_ctz32 (6) = 1 403 ecb_ctz32 (6) = 1
387 404
388=item int ecb_popcount32 (uint32_t x) 405=item int ecb_popcount32 (uint32_t x)
… …
394 411
395=item uint32_t ecb_bswap16 (uint32_t x) 412=item uint32_t ecb_bswap16 (uint32_t x)
396 413
397=item uint32_t ecb_bswap32 (uint32_t x) 414=item uint32_t ecb_bswap32 (uint32_t x)
398 415
399These two functions return the value of the 16-bit (32-bit) variable 416These two functions return the value of the 16-bit (32-bit) value C<x>
400C<x> after reversing the order of bytes. 417after reversing the order of bytes (0x11223344 becomes 0x44332211).
401 418
402=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count) 419=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
403 420
404=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count) 421=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
405 422
406These two functions return the value of C<x> after shifting all the bits 423These two functions return the value of C<x> after rotating all the bits
407by C<count> positions to the right or left respectively. 424by C<count> positions to the right or left respectively.
408 425
426Current GCC versions understand these functions and usually compile them
427to "optimal" code (e.g. a single C<roll> on x86).
428
409=back 429=back
410 430
411=head2 ARITHMETIC 431=head2 ARITHMETIC
412 432
413=over 4 433=over 4
414 434
415=item x = ecb_mod (m, n) 435=item x = ecb_mod (m, n)
416 436
417Returns the positive remainder of the modulo operation between C<m> and 437Returns the positive remainder of the modulo operation between C<m> and
418C<n>. Unlike the C modulo operator C<%>, this function ensures that the 438C<n>, using floored division. Unlike the C modulo operator C<%>, this
419return value is always positive). 439function ensures that the return value is always positive and that the two
440numbers I<m> and I<m' = m + i * n> result in the same value modulo I<n> -
441the C<%> operator usually has a behaviour change at C<m = 0>.
420 442
421C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be 443C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
422negatable, that is, both C<m> and C<-m> must be representable in its 444negatable, that is, both C<m> and C<-m> must be representable in its
423type. 445type.
424 446
447Current GCC versions compile this into an efficient branchless sequence on
448many systems.
449
450For example, when you want to rotate forward through the members of an
451array for increasing C<m> (which might be negative), then you should use
452C<ecb_mod>, as the C<%> operator might give either negative results, or
453change direction for negative values:
454
455 for (m = -100; m <= 100; ++m)
456 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
457
425=back 458=back
426 459
427=head2 UTILITY 460=head2 UTILITY
428 461
429=over 4 462=over 4
430 463
431=item element_count = ecb_array_length (name) [MACRO] 464=item element_count = ecb_array_length (name)
432 465
433Returns the number of elements in the array C<name>. For example: 466Returns the number of elements in the array C<name>. For example:
434 467
435 int primes[] = { 2, 3, 5, 7, 11 }; 468 int primes[] = { 2, 3, 5, 7, 11 };
436 int sum = 0; 469 int sum = 0;

Diff Legend

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