ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
Revision: 1.4
Committed: Thu May 26 20:05:25 2011 UTC (13 years, 1 month ago) by root
Branch: MAIN
Changes since 1.3: +2 -2 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.3 =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
11 root 1.1
12     =head2 GCC ATTRIBUTES
13    
14 root 1.3 blabla where to put, what others
15    
16 root 1.1 =over 4
17    
18 root 1.2 =item ecb_attribute ((attrs...))
19 root 1.1
20 root 1.2 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 root 1.3 =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 root 1.2 =item ecb_noinline
41    
42 root 1.3 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 root 1.2 =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    
58     =back
59 root 1.1
60     =head2 OPTIMISATION HINTS
61    
62     =over 4
63    
64     =item bool ecb_is_constant(expr)
65    
66 root 1.3 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     }
91    
92 root 1.1 =item bool ecb_expect(expr,value)
93    
94     =item bool ecb_unlikely(bool)
95    
96     =item bool ecb_likely(bool)
97    
98     =item bool ecb_assume(cond)
99    
100     =item bool ecb_unreachable()
101    
102     =item bool ecb_prefetch(addr,rw,locality)
103    
104 root 1.2 =back
105 root 1.1
106     =head2 BIT FIDDLING / BITSTUFFS
107    
108 root 1.4 =over 4
109    
110 root 1.3 =item bool ecb_big_endian ()
111    
112     =item bool ecb_little_endian ()
113    
114     =item int ecb_ctz32 (uint32_t x)
115    
116     =item int ecb_popcount32 (uint32_t x)
117    
118     =item uint32_t ecb_bswap32 (uint32_t x)
119    
120     =item uint32_t ecb_bswap16 (uint32_t x)
121    
122     =item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
123    
124     =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
125    
126     =back
127 root 1.1
128     =head2 ARITHMETIC
129    
130 root 1.3 =over 4
131    
132     =item x = ecb_mod (m, n) [MACRO]
133    
134     =back
135 root 1.1
136     =head2 UTILITY
137    
138 root 1.3 =over 4
139    
140     =item ecb_array_length (name) [MACRO]
141    
142     =back
143 root 1.1
144