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.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
… …
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