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

File Contents

# Content
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
11
12 =head2 GCC ATTRIBUTES
13
14 blabla where to put, what others
15
16 =over 4
17
18 =item ecb_attribute ((attrs...))
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
58 =back
59
60 =head2 OPTIMISATION HINTS
61
62 =over 4
63
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 function 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 =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 =back
105
106 =head2 BIT FIDDLING / BITSTUFFS
107
108 =over 4
109
110 =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
128 =head2 ARITHMETIC
129
130 =over 4
131
132 =item x = ecb_mod (m, n) [MACRO]
133
134 =back
135
136 =head2 UTILITY
137
138 =over 4
139
140 =item ecb_array_length (name) [MACRO]
141
142 =back
143
144