lib/silcutil/silcbitops.h

   1 /*
   2
   3   silcbitops.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 Pekka Riikonen
   8
   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.
  12
  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.
  17
  18 */
  19
  20 /****h* silcutil/SILC Bit Operations Interface
  21  *
  22  * DESCRIPTION
  23  *
  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.
  27  *
  28  * Example with a pre-allocate bitmap:
  29  *
  30  * // Declare bitmap of size of 500 bits
  31  * SILC_BITMAP_DECLARE(bitmap, 500);
  32  * int bitmap_size = SILC_BITMAP_SIZE(500);
  33  *
  34  * // Set 0 bit
  35  * silc_bit_set(bitmap, bitmap_size, 0);
  36  *
  37  * // Set bit number 100
  38  * silc_bit_set(bitmap, bitmap_size, 100);
  39  *
  40  * // Find first set bit from the bitmap
  41  * bit = silc_bit_ffs(bitmap, bitmap_size);
  42  *
  43  * // Find next set bit from the bitmap
  44  * bit = silc_bit_fns(bitmap, bitmap_size, bit);
  45  *
  46  * // Clear bit number 100
  47  * silc_bit_set(bitmap, bitmap_size, 100);
  48  *
  49  ***/
  50
  51 #ifndef SILCBITOPS_H
  52 #define SILCBITOPS_H
  53
  54 #define SILC_BIT_SIZE (SILC_SIZEOF_LONG * 8)
  55
  56 /****d* silcutil/SilcBitOpAPI/SILC_BITMAP_DECLARE
  57  *
  58  * NAME
  59  *
  60  *    #define SILC_BITMAP_DECLARE(name, bits)
  61  *
  62  * DESCRIPTION
  63  *
  64  *    Macro that can be used to declare a pre-allocated bitmap named `name' of
  65  *    size of `bits' many bits.
  66  *
  67  ***/
  68 #define SILC_BITMAP_DECLARE(name, bits)         \
  69   unsigned long name[SILC_BITMAP_SIZE(bits)]
  70
  71 /****d* silcutil/SilcBitOpAPI/SILC_BITMAP_SIZE
  72  *
  73  * NAME
  74  *
  75  *    #define SILC_BITMAP_SIZE(bits)
  76  *
  77  * DESCRIPTION
  78  *
  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.
  82  *
  83  ***/
  84 #define SILC_BITMAP_SIZE(bits) (((bits) + SILC_BIT_SIZE) / SILC_BIT_SIZE)
  85
  86 /****f* silcutil/SilcBitOpAPI/silc_bit_set
  87  *
  88  * SYNOPSIS
  89  *
  90  *    SilcBool silc_bit_set(volatile unsigned long *bitmap,
  91  *                          SilcUInt32 bitmap_size, SilcUInt32 bit);
  92  *
  93  * DESCRIPTION
  94  *
  95  *    Set bit number `bit' in the `bitmap' of size of `bitmap_size'.  Returns
  96  *    FALSE on error.
  97  *
  98  ***/
  99 SilcBool silc_bit_set(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 100                       SilcUInt32 bit);
 101
 102 /****f* silcutil/SilcBitOpAPI/silc_bit_clear
 103  *
 104  * SYNOPSIS
 105  *
 106  *    SilcBool silc_bit_clear(volatile unsigned long *bitmap,
 107  *                           SilcUInt32 bitmap_size,  SilcUInt32 bit);
 108  *
 109  * DESCRIPTION
 110  *
 111  *    Clear bit number `bit' in the `bitmap' of size of `bitmap_size'.
 112  *    Returns FALSE on error.
 113  *
 114  ***/
 115 SilcBool silc_bit_clear(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 116                         SilcUInt32 bit);
 117
 118 /****f* silcutil/SilcBitOpAPI/silc_bit_toggle
 119  *
 120  * SYNOPSIS
 121  *
 122  *    SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
 123  *                             SilcUInt32 bitmap_size, SilcUInt32 bit);
 124  *
 125  * DESCRIPTION
 126  *
 127  *    Toggle bit number `bit' in the `bitmap' of size of `bitmap_size'.
 128  *    Returns FALSE on error.
 129  *
 130  ***/
 131 SilcBool silc_bit_toggle(volatile unsigned long *bitmap,
 132                          SilcUInt32 bitmap_size, SilcUInt32 bit);
 133
 134 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_set
 135  *
 136  * SYNOPSIS
 137  *
 138  *    int silc_bit_test_and_set(volatile unsigned long *bitmap,
 139  *                              SilcUInt32 bitmap_size, SilcUInt32 bit);
 140  *
 141  * DESCRIPTION
 142  *
 143  *    Set bit number `bit' in the `bitmap' of size of `bitmap_size' and
 144  *    return the value before setting.  Returns -1 on error.
 145  *
 146  ***/
 147 int silc_bit_test_and_set(volatile unsigned long *bitmap,
 148                           SilcUInt32 bitmap_size, SilcUInt32 bit);
 149
 150 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_clear
 151  *
 152  * SYNOPSIS
 153  *
 154  *    int silc_bit_test_and_clear(volatile unsigned long *bitmap,
 155  *                               SilcUInt32 bitmap_size,  SilcUInt32 bit);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Clear bit number `bit' in the `bitmap' of size of `bitmap_size' and
 160  *    return the value before setting.  Returns -1 on error.
 161  *
 162  ***/
 163 int silc_bit_test_and_clear(volatile unsigned long *bitmap,
 164                             SilcUInt32 bitmap_size, SilcUInt32 bit);
 165
 166 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_toggle
 167  *
 168  * SYNOPSIS
 169  *
 170  *    int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
 171  *                                 SilcUInt32 bitmap_size, SilcUInt32 bit);
 172  *
 173  * DESCRIPTION
 174  *
 175  *    Toggle bit number `bit' in the `bitmap' of size of `bitmap_size' and
 176  *    return the value before setting.  Returns -1 on error.
 177  *
 178  ***/
 179 int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
 180                              SilcUInt32 bitmap_size, SilcUInt32 bit);
 181
 182 /****f* silcutil/SilcBitOpAPI/silc_bit_get
 183  *
 184  * SYNOPSIS
 185  *
 186  *    int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 187  *                     ,SilcUInt32 bit);
 188  *
 189  * DESCRIPTION
 190  *
 191  *    Returns the value of the bit number `bit' or -1 on error.
 192  *
 193  ***/
 194 int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 195                  SilcUInt32 bit);
 196
 197 /****f* silcutil/SilcBitOpAPI/silc_bit_ffs
 198  *
 199  * SYNOPSIS
 200  *
 201  *    int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 202  *
 203  * DESCRIPTION
 204  *
 205  *    Returns the bit number of the first set bit in the `bitmap' of size
 206  *    of `bitmap_size'.  Returns -1 on error or there were no set bits.
 207  *
 208  ***/
 209 int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 210
 211 /****f* silcutil/SilcBitOpAPI/silc_bit_ffz
 212  *
 213  * SYNOPSIS
 214  *
 215  *    int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 216  *
 217  * DESCRIPTION
 218  *
 219  *    Returns the bit number of the first zero bit in the `bitmap' of size
 220  *    of `bitmap_size'.  Returns -1 on error or there were no zero bits.
 221  *
 222  ***/
 223 int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 224
 225 /****f* silcutil/SilcBitOpAPI/silc_bit_fns
 226  *
 227  * SYNOPSIS
 228  *
 229  *    int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 230  *                     SilcUInt32 offset);
 231  *
 232  * DESCRIPTION
 233  *
 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  *    there were no more set bits.
 237  *
 238  ***/
 239 int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 240                  SilcUInt32 offset);
 241
 242 /****f* silcutil/SilcBitOpAPI/silc_bit_fnz
 243  *
 244  * SYNOPSIS
 245  *
 246  *    int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 247  *                     SilcUInt32 offset);
 248  *
 249  * DESCRIPTION
 250  *
 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  *    there were no more zero bits.
 254  *
 255  ***/
 256 int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 257                  SilcUInt32 offset);
 258
 259 /****f* silcutil/SilcBitOpAPI/silc_bit_clear_bitmap
 260  *
 261  * SYNOPSIS
 262  *
 263  *    void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
 264  *                               SilcUInt32 bitmap_size);
 265  *
 266  * DESCRIPTION
 267  *
 268  *    Clears the whole bitmap.
 269  *
 270  ***/
 271 void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
 272                            SilcUInt32 bitmap_size);
 273
 274 #endif /* SILCBITOPS_H */