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.22 by root, Fri May 27 00:18:14 2011 UTC

… …
55is usually implemented as a macro. Specifically, a "bool" in this manual 55is usually implemented as a macro. Specifically, a "bool" in this manual
56refers to any kind of boolean value, not a specific type. 56refers to any kind of boolean value, not a specific type.
57 57
58=head2 GCC ATTRIBUTES 58=head2 GCC ATTRIBUTES
59 59
60blabla where to put, what others 60A major part of libecb deals with GCC attributes. These are additional
61attributes that you cna assign to functions, variables and sometimes even
62types - much like C<const> or C<volatile> in C.
63
64While GCC allows declarations to show up in many surprising places,
65but not in many expeted places, the safest way is to put attribute
66declarations before the whole declaration:
67
68 ecb_const int mysqrt (int a);
69 ecb_unused int i;
70
71For variables, it is often nicer to put the attribute after the name, and
72avoid multiple declarations using commas:
73
74 int i ecb_unused;
61 75
62=over 4 76=over 4
63 77
64=item ecb_attribute ((attrs...)) 78=item ecb_attribute ((attrs...))
65 79
… …
105 { 119 {
106 puts (errline); 120 puts (errline);
107 abort (); 121 abort ();
108 } 122 }
109 123
110In this case, the compiler would probbaly be smart enough to decude it on 124In this case, the compiler would probably be smart enough to deduce it on
111it's own, so this is mainly useful for declarations. 125its own, so this is mainly useful for declarations.
112 126
113=item ecb_const 127=item ecb_const
114 128
115Declares that the function only depends on the values of it's arguments, 129Declares that the function only depends on the values of its arguments,
116much like a mathematical function. It specifically does not read or write 130much like a mathematical function. It specifically does not read or write
117any memory any arguments might point to, global variables, or call any 131any memory any arguments might point to, global variables, or call any
118non-const functions. It also must not have any side effects. 132non-const functions. It also must not have any side effects.
119 133
120Such a function can be optimised much more aggressively by the compiler - 134Such a function can be optimised much more aggressively by the compiler -
121for example, multiple calls with the same arguments can be optimised into 135for 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 136a single call, which wouldn't be possible if the compiler would have to
123expect any side effects. 137expect any side effects.
124 138
125It is best suited for functions in the sense of mathematical functions, 139It is best suited for functions in the sense of mathematical functions,
126such as a function return the square root of its input argument. 140such as a function returning the square root of its input argument.
127 141
128Not suited would be a function that calculates the hash of some memory 142Not 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 143area you pass in, prints some messages or looks at a global variable to
130decide on rounding. 144decide on rounding.
131 145
… …
154possible. 168possible.
155 169
156The compiler reacts by trying to place hot functions near to each other in 170The compiler reacts by trying to place hot functions near to each other in
157memory. 171memory.
158 172
159Whether a function is hot or not often depend son the whole program, 173Whether 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 174and less on the function itself. C<ecb_cold> is likely more useful in
161practise. 175practise.
162 176
163=item ecb_cold 177=item ecb_cold
164 178
… …
169 183
170In addition to placing cold functions together (or at least away from hot 184In addition to placing cold functions together (or at least away from hot
171functions), this knowledge can be used in other ways, for example, the 185functions), this knowledge can be used in other ways, for example, the
172function will be optimised for size, as opposed to speed, and codepaths 186function will be optimised for size, as opposed to speed, and codepaths
173leading to calls to those functions can automatically be marked as if 187leading to calls to those functions can automatically be marked as if
174C<ecb_unlikel> had been used to reach them. 188C<ecb_unlikely> had been used to reach them.
175 189
176Good examples for such functions would be error reporting functions, or 190Good examples for such functions would be error reporting functions, or
177functions only called in exceptional or rare cases. 191functions only called in exceptional or rare cases.
178 192
179=item ecb_artificial 193=item ecb_artificial
… …
394 408
395=item uint32_t ecb_bswap16 (uint32_t x) 409=item uint32_t ecb_bswap16 (uint32_t x)
396 410
397=item uint32_t ecb_bswap32 (uint32_t x) 411=item uint32_t ecb_bswap32 (uint32_t x)
398 412
399These two functions return the value of the 16-bit (32-bit) variable 413These two functions return the value of the 16-bit (32-bit) value C<x>
400C<x> after reversing the order of bytes. 414after reversing the order of bytes (0x11223344 becomes 0x44332211).
401 415
402=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count) 416=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
403 417
404=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count) 418=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
405 419
406These two functions return the value of C<x> after shifting all the bits 420These two functions return the value of C<x> after rotating all the bits
407by C<count> positions to the right or left respectively. 421by C<count> positions to the right or left respectively.
422
423Current GCC versions understand these functions and usually compile them
424to "optimal" code (e.g. a single C<roll> on x86).
408 425
409=back 426=back
410 427
411=head2 ARITHMETIC 428=head2 ARITHMETIC
412 429
… …
414 431
415=item x = ecb_mod (m, n) 432=item x = ecb_mod (m, n)
416 433
417Returns the positive remainder of the modulo operation between C<m> and 434Returns the positive remainder of the modulo operation between C<m> and
418C<n>. Unlike the C modulo operator C<%>, this function ensures that the 435C<n>. Unlike the C modulo operator C<%>, this function ensures that the
419return value is always positive). 436return value is always positive - ISO C guarantees very little when
437negative numbers are used with C<%>.
420 438
421C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be 439C<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 440negatable, that is, both C<m> and C<-m> must be representable in its
423type. 441type.
424 442

Diff Legend

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