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

Comparing libecb/ecb.pod (file contents):
Revision 1.19 by sf-exg, Fri May 27 00:04:05 2011 UTC vs.
Revision 1.26 by sf-exg, Wed Jun 1 00:57:14 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 can 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 expected 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
… …
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 C<m> modulo C<n>, which is the same as the positive remainder
438of the division operation between C<m> and C<n>, using floored
418C<n>. Unlike the C modulo operator C<%>, this function ensures that the 439division. Unlike the C remainder operator C<%>, this function ensures that
419return value is always positive). 440the return value is always positive and that the two numbers I<m> and
441I<m' = m + i * n> result in the same value modulo I<n> - in other words,
442C<ecb_mod> implements the mathematical modulo operation, which is missing
443in the language.
420 444
421C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be 445C<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 446negatable, that is, both C<m> and C<-m> must be representable in its
423type. 447type (this typically includes the minimum signed integer value, the same
448limitation as for C</> and C<%> in C).
449
450Current GCC versions compile this into an efficient branchless sequence on
451many systems.
452
453For example, when you want to rotate forward through the members of an
454array for increasing C<m> (which might be negative), then you should use
455C<ecb_mod>, as the C<%> operator might give either negative results, or
456change direction for negative values:
457
458 for (m = -100; m <= 100; ++m)
459 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
424 460
425=back 461=back
426 462
427=head2 UTILITY 463=head2 UTILITY
428 464
429=over 4 465=over 4
430 466
431=item element_count = ecb_array_length (name) [MACRO] 467=item element_count = ecb_array_length (name)
432 468
433Returns the number of elements in the array C<name>. For example: 469Returns the number of elements in the array C<name>. For example:
434 470
435 int primes[] = { 2, 3, 5, 7, 11 }; 471 int primes[] = { 2, 3, 5, 7, 11 };
436 int sum = 0; 472 int sum = 0;

Diff Legend

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