|
|
1 | =head1 LIBECB |
|
|
2 | |
|
|
3 | You suck, we don't(tm) |
|
|
4 | |
|
|
5 | =head2 ABOUT THE HEADER |
|
|
6 | |
|
|
7 | - how to include it |
|
|
8 | - it includes inttypes.h |
|
|
9 | - no .a |
|
|
10 | - whats a bool |
| 1 | |
11 | |
| 2 | =head2 GCC ATTRIBUTES |
12 | =head2 GCC ATTRIBUTES |
| 3 | |
13 | |
|
|
14 | blabla where to put, what others |
|
|
15 | |
| 4 | =over 4 |
16 | =over 4 |
| 5 | |
17 | |
| 6 | =item ecb_attribute(attrlist) |
18 | =item ecb_attribute ((attrs...)) |
| 7 | =item ecb_noinline ecb_attribute ((noinline)) |
|
|
| 8 | =item ecb_noreturn ecb_attribute ((noreturn)) |
|
|
| 9 | =item ecb_unused ecb_attribute ((unused)) |
|
|
| 10 | =item ecb_const ecb_attribute ((const)) |
|
|
| 11 | =item ecb_pure ecb_attribute ((pure)) |
|
|
| 12 | =item ecb_hot ecb_attribute ((hot)) /* 4.3 */ |
|
|
| 13 | =item ecb_cold ecb_attribute ((cold)) /* 4.3 */ |
|
|
| 14 | |
19 | |
|
|
20 | A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and |
|
|
21 | to nothing on other compilers, so the effect is that only GCC sees these. |
|
|
22 | |
|
|
23 | =item ecb_unused |
|
|
24 | |
|
|
25 | Marks a function or a variable as "unused", which simply suppresses a |
|
|
26 | warning by GCC when it detects it as unused. This is useful when you e.g. |
|
|
27 | declare a variable but do not always use it: |
|
|
28 | |
|
|
29 | { |
|
|
30 | int var ecb_unused; |
|
|
31 | |
|
|
32 | #ifdef SOMECONDITION |
|
|
33 | var = ...; |
|
|
34 | return var; |
|
|
35 | #else |
|
|
36 | return 0; |
|
|
37 | #endif |
|
|
38 | } |
|
|
39 | |
|
|
40 | =item ecb_noinline |
|
|
41 | |
|
|
42 | Prevent a function from being inlined - it might be optimsied away, but |
|
|
43 | not inlined into other functions. This is useful if you know your function |
|
|
44 | is rarely called and large enough for inlining not to be helpful. |
|
|
45 | |
|
|
46 | =item ecb_noreturn |
|
|
47 | |
|
|
48 | =item ecb_const |
|
|
49 | |
|
|
50 | =item ecb_pure |
|
|
51 | |
|
|
52 | =item ecb_hot |
|
|
53 | |
|
|
54 | =item ecb_cold |
|
|
55 | |
|
|
56 | =item ecb_artificial |
|
|
57 | |
| 15 | =back |
58 | =back |
| 16 | |
59 | |
| 17 | =head2 OPTIMISATION HINTS |
60 | =head2 OPTIMISATION HINTS |
| 18 | |
61 | |
| 19 | =over 4 |
62 | =over 4 |
| 20 | |
63 | |
| 21 | =item bool ecb_is_constant(expr) |
64 | =item bool ecb_is_constant(expr) |
|
|
65 | |
|
|
66 | Returns true iff the expression can be deduced to be a compile-time |
|
|
67 | constant, and false otherwise. |
|
|
68 | |
|
|
69 | For example, when you have a C<rndm16> function that returns a 16 bit |
|
|
70 | random number, and you have a function that maps this to a range from |
|
|
71 | 0..n-1, then you could use this inline fucntion in a header file: |
|
|
72 | |
|
|
73 | ecb_inline uint32_t |
|
|
74 | rndm (uint32_t n) |
|
|
75 | { |
|
|
76 | return n * (uint32_t)rndm16 ()) >> 16; |
|
|
77 | } |
|
|
78 | |
|
|
79 | However, for powers of two, you could use a normal mask, but that is only |
|
|
80 | worth it if, at compile time, you can detect this case. This is the case |
|
|
81 | when the passed number is a constant and also a power of two (C<n & (n - |
|
|
82 | 1) == 0>): |
|
|
83 | |
|
|
84 | ecb_inline uint32_t |
|
|
85 | rndm (uint32_t n) |
|
|
86 | { |
|
|
87 | return is_constant (n) && !(n & (n - 1)) |
|
|
88 | ? rndm16 () & (num - 1) |
|
|
89 | : (uint32_t)rndm16 ()) >> 16; |
|
|
90 | } |
| 22 | |
91 | |
| 23 | =item bool ecb_expect(expr,value) |
92 | =item bool ecb_expect(expr,value) |
| 24 | |
93 | |
| 25 | =item bool ecb_unlikely(bool) |
94 | =item bool ecb_unlikely(bool) |
| 26 | |
95 | |
| … | |
… | |
| 30 | |
99 | |
| 31 | =item bool ecb_unreachable() |
100 | =item bool ecb_unreachable() |
| 32 | |
101 | |
| 33 | =item bool ecb_prefetch(addr,rw,locality) |
102 | =item bool ecb_prefetch(addr,rw,locality) |
| 34 | |
103 | |
| 35 | =back |
104 | =back |
| 36 | |
105 | |
| 37 | =head2 BIT FIDDLING / BITSTUFFS |
106 | =head2 BIT FIDDLING / BITSTUFFS |
| 38 | |
107 | |
|
|
108 | =over 4 |
|
|
109 | |
| 39 | bool ecb_big_endian (); |
110 | =item bool ecb_big_endian () |
|
|
111 | |
| 40 | bool ecb_little_endian (); |
112 | =item bool ecb_little_endian () |
|
|
113 | |
| 41 | int ecb_ctz32 (uint32_t x); |
114 | =item int ecb_ctz32 (uint32_t x) |
|
|
115 | |
| 42 | int ecb_popcount32 (uint32_t x); |
116 | =item int ecb_popcount32 (uint32_t x) |
|
|
117 | |
| 43 | uint32_t ecb_bswap32 (uint32_t x); |
118 | =item uint32_t ecb_bswap32 (uint32_t x) |
|
|
119 | |
| 44 | uint32_t ecb_bswap16 (uint32_t x); |
120 | =item uint32_t ecb_bswap16 (uint32_t x) |
|
|
121 | |
| 45 | uint32_t ecb_rotr32 (uint32_t x, unsigned int count); |
122 | =item uint32_t ecb_rotr32 (uint32_t x, unsigned int count) |
|
|
123 | |
| 46 | uint32_t ecb_rotl32 (uint32_t x, unsigned int count); |
124 | =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count) |
|
|
125 | |
|
|
126 | =back |
| 47 | |
127 | |
| 48 | =head2 ARITHMETIC |
128 | =head2 ARITHMETIC |
| 49 | |
129 | |
| 50 | x = ecb_mod (m, n) |
130 | =over 4 |
|
|
131 | |
|
|
132 | =item x = ecb_mod (m, n) [MACRO] |
|
|
133 | |
|
|
134 | =back |
| 51 | |
135 | |
| 52 | =head2 UTILITY |
136 | =head2 UTILITY |
| 53 | |
137 | |
|
|
138 | =over 4 |
|
|
139 | |
| 54 | ecb_array_length (name) |
140 | =item ecb_array_length (name) [MACRO] |
|
|
141 | |
|
|
142 | =back |
| 55 | |
143 | |
| 56 | |
144 | |
