5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/SILC Bit Operations Interface
24 * Bit operations interface. The interface can be used to set, clear and
25 * find bits in an arbitrarily large bitmap. The interface does not support
26 * setting the bits atomically.
28 * Example with a pre-allocated bitmap:
30 * // Declare bitmap of size of 500 bits
31 * SILC_BITMAP_DECLARE(bitmap, 500);
32 * int bitmap_size = SILC_BITMAP_SIZE(500);
35 * silc_bit_set(bitmap, bitmap_size, 0);
37 * // Set bit number 100
38 * silc_bit_set(bitmap, bitmap_size, 100);
40 * // Find first set bit from the bitmap
41 * bit = silc_bit_ffs(bitmap, bitmap_size);
43 * // Find next set bit from the bitmap
44 * bit = silc_bit_fns(bitmap, bitmap_size, bit + 1);
46 * // Clear bit number 100
47 * silc_bit_set(bitmap, bitmap_size, 100);
54 #define SILC_BIT_SIZE (SILC_SIZEOF_LONG * 8)
56 /****d* silcutil/SilcBitOpAPI/SILC_BITMAP_DECLARE
60 * #define SILC_BITMAP_DECLARE(name, bits)
64 * Macro that can be used to declare a pre-allocated bitmap named `name' of
65 * size of `bits' many bits.
68 #define SILC_BITMAP_DECLARE(name, bits) \
69 unsigned long name[SILC_BITMAP_SIZE(bits)]
71 /****d* silcutil/SilcBitOpAPI/SILC_BITMAP_SIZE
75 * #define SILC_BITMAP_SIZE(bits)
79 * Macro that returns the size of a bitmap array of size of `bits' many
80 * bits. The returned size can be given as argument to the SILC Bit
81 * Operations API functions.
84 #define SILC_BITMAP_SIZE(bits) (((bits) + SILC_BIT_SIZE) / SILC_BIT_SIZE)
86 /****f* silcutil/SilcBitOpAPI/silc_bit_set
90 * SilcBool silc_bit_set(volatile unsigned long *bitmap,
91 * SilcUInt32 bitmap_size, SilcUInt32 bit);
95 * Set bit number `bit' in the `bitmap' of size of `bitmap_size'. Returns
99 SilcBool silc_bit_set(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
102 /****f* silcutil/SilcBitOpAPI/silc_bit_clear
106 * SilcBool silc_bit_clear(volatile unsigned long *bitmap,
107 * SilcUInt32 bitmap_size, SilcUInt32 bit);
111 * Clear bit number `bit' in the `bitmap' of size of `bitmap_size'.
112 * Returns FALSE on error.
115 SilcBool silc_bit_clear(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
118 /****f* silcutil/SilcBitOpAPI/silc_bit_toggle
122 * SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
123 * SilcUInt32 bitmap_size, SilcUInt32 bit);
127 * Toggle bit number `bit' in the `bitmap' of size of `bitmap_size'.
128 * Returns FALSE on error.
131 SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
132 SilcUInt32 bitmap_size, SilcUInt32 bit);
134 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_set
138 * int silc_bit_test_and_set(volatile unsigned long *bitmap,
139 * SilcUInt32 bitmap_size, SilcUInt32 bit);
143 * Set bit number `bit' in the `bitmap' of size of `bitmap_size' and
144 * return the value before setting. Returns -1 on error.
147 int silc_bit_test_and_set(volatile unsigned long *bitmap,
148 SilcUInt32 bitmap_size, SilcUInt32 bit);
150 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_clear
154 * int silc_bit_test_and_clear(volatile unsigned long *bitmap,
155 * SilcUInt32 bitmap_size, SilcUInt32 bit);
159 * Clear bit number `bit' in the `bitmap' of size of `bitmap_size' and
160 * return the value before setting. Returns -1 on error.
163 int silc_bit_test_and_clear(volatile unsigned long *bitmap,
164 SilcUInt32 bitmap_size, SilcUInt32 bit);
166 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_toggle
170 * int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
171 * SilcUInt32 bitmap_size, SilcUInt32 bit);
175 * Toggle bit number `bit' in the `bitmap' of size of `bitmap_size' and
176 * return the value before setting. Returns -1 on error.
179 int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
180 SilcUInt32 bitmap_size, SilcUInt32 bit);
182 /****f* silcutil/SilcBitOpAPI/silc_bit_get
186 * int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
191 * Returns the value of the bit number `bit' or -1 on error.
194 int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
197 /****f* silcutil/SilcBitOpAPI/silc_bit_ffs
201 * int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
205 * Returns the bit number of the first set bit in the `bitmap' of size
206 * of `bitmap_size'. Returns -1 on error or when there were no set bits.
209 int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
211 /****f* silcutil/SilcBitOpAPI/silc_bit_ffz
215 * int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
219 * Returns the bit number of the first zero bit in the `bitmap' of size
220 * of `bitmap_size'. Returns -1 on error or when there were no zero bits.
223 int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
225 /****f* silcutil/SilcBitOpAPI/silc_bit_fns
229 * int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
230 * SilcUInt32 offset);
234 * Returns the bit number of the next set bit in the `bitmap' of size
235 * of `bitmap_size' starting at bit `offset'. Returns -1 on error or
236 * when there were no more set bits.
239 int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
242 /****f* silcutil/SilcBitOpAPI/silc_bit_fnz
246 * int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
247 * SilcUInt32 offset);
251 * Returns the bit number of the next zero bit in the `bitmap' of size
252 * of `bitmap_size' starting at bit `offset'. Returns -1 on error or
253 * when there were no more zero bits.
256 int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
259 /****f* silcutil/SilcBitOpAPI/silc_bit_clear_bitmap
263 * void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
264 * SilcUInt32 bitmap_size);
268 * Clears the whole bitmap.
271 void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
272 SilcUInt32 bitmap_size);
274 #endif /* SILCBITOPS_H */