cvsroot/libecb/ecb.pod

=head1 LIBECB

You suck, we don't(tm)

=head2 ABOUT THE HEADER

- how to include it
- it includes inttypes.h
- no .a
- whats a bool

=head2 GCC ATTRIBUTES

blabla where to put, what others

=over 4

=item ecb_attribute ((attrs...))

A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and
to nothing on other compilers, so the effect is that only GCC sees these.

=item ecb_unused

Marks a function or a variable as "unused", which simply suppresses a
warning by GCC when it detects it as unused. This is useful when you e.g.
declare a variable but do not always use it:

   {
     int var ecb_unused;

     #ifdef SOMECONDITION
        var = ...;
        return var;
     #else
        return 0;
     #endif
   }

=item ecb_noinline

Prevent a function from being inlined - it might be optimsied away, but
not inlined into other functions. This is useful if you know your function
is rarely called and large enough for inlining not to be helpful.

=item ecb_noreturn

=item ecb_const

=item ecb_pure

=item ecb_hot

=item ecb_cold

=item ecb_artificial

=back

=head2 OPTIMISATION HINTS

=over 4

=item bool ecb_is_constant(expr)

Returns true iff the expression can be deduced to be a compile-time
constant, and false otherwise.

For example, when you have a C<rndm16> function that returns a 16 bit
random number, and you have a function that maps this to a range from
0..n-1, then you could use this inline fucntion in a header file:

  ecb_inline uint32_t
  rndm (uint32_t n)
  {
    return n * (uint32_t)rndm16 ()) >> 16;
  }

However, for powers of two, you could use a normal mask, but that is only
worth it if, at compile time, you can detect this case. This is the case
when the passed number is a constant and also a power of two (C<n & (n -
1) == 0>):

  ecb_inline uint32_t
  rndm (uint32_t n)
  {
    return is_constant (n) && !(n & (n - 1))
      ? rndm16 () & (num - 1)
      : (uint32_t)rndm16 ()) >> 16;
  }

  

=item bool ecb_expect(expr,value)

=item bool ecb_unlikely(bool)

=item bool ecb_likely(bool)

=item bool ecb_assume(cond)

=item bool ecb_unreachable()

=item bool ecb_prefetch(addr,rw,locality)

=back

=head2 BIT FIDDLING / BITSTUFFS

=item bool ecb_big_endian ()

=item bool ecb_little_endian ()

=item int ecb_ctz32 (uint32_t x)

=item int ecb_popcount32 (uint32_t x)

=item uint32_t ecb_bswap32 (uint32_t x)

=item uint32_t ecb_bswap16 (uint32_t x)

=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)

=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)

=back

=head2 ARITHMETIC

=over 4

=item x = ecb_mod (m, n) [MACRO]

=back

=head2 UTILITY

=over 4

=item ecb_array_length (name) [MACRO]

=back


Revision:	1.3
Committed:	Thu May 26 20:04:38 2011 UTC (15 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.2:	+88 -12 lines
Log Message:	* empty log message *
#	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
93
94	root	1.1	=item bool ecb_expect(expr,value)
95
96			=item bool ecb_unlikely(bool)
97
98			=item bool ecb_likely(bool)
99
100			=item bool ecb_assume(cond)
101
102			=item bool ecb_unreachable()
103
104			=item bool ecb_prefetch(addr,rw,locality)
105
106	root	1.2	=back
107	root	1.1
108			=head2 BIT FIDDLING / BITSTUFFS
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