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-allocated 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 + 1);
  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 and sets silc_errno.
  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 and sets silc_errno.
 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 and sets silc_errno.
 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 and sets
 145  *    silc_errno.
 146  *
 147  ***/
 148 int silc_bit_test_and_set(volatile unsigned long *bitmap,
 149                           SilcUInt32 bitmap_size, SilcUInt32 bit);
 150
 151 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_clear
 152  *
 153  * SYNOPSIS
 154  *
 155  *    int silc_bit_test_and_clear(volatile unsigned long *bitmap,
 156  *                               SilcUInt32 bitmap_size,  SilcUInt32 bit);
 157  *
 158  * DESCRIPTION
 159  *
 160  *    Clear bit number `bit' in the `bitmap' of size of `bitmap_size' and
 161  *    return the value before setting.  Returns -1 on error and sets
 162  *    silc_errno.
 163  *
 164  ***/
 165 int silc_bit_test_and_clear(volatile unsigned long *bitmap,
 166                             SilcUInt32 bitmap_size, SilcUInt32 bit);
 167
 168 /****f* silcutil/SilcBitOpAPI/silc_bit_test_and_toggle
 169  *
 170  * SYNOPSIS
 171  *
 172  *    int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
 173  *                                 SilcUInt32 bitmap_size, SilcUInt32 bit);
 174  *
 175  * DESCRIPTION
 176  *
 177  *    Toggle bit number `bit' in the `bitmap' of size of `bitmap_size' and
 178  *    return the value before setting.  Returns -1 on error and sets
 179  *    silc_errno.
 180  *
 181  ***/
 182 int silc_bit_test_and_toggle(volatile unsigned long *bitmap,
 183                              SilcUInt32 bitmap_size, SilcUInt32 bit);
 184
 185 /****f* silcutil/SilcBitOpAPI/silc_bit_get
 186  *
 187  * SYNOPSIS
 188  *
 189  *    int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 190  *                     SilcUInt32 bit);
 191  *
 192  * DESCRIPTION
 193  *
 194  *    Returns the value of the bit number `bit' or -1 on error and sets
 195  *    silc_errno.
 196  *
 197  ***/
 198 int silc_bit_get(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 199                  SilcUInt32 bit);
 200
 201 /****f* silcutil/SilcBitOpAPI/silc_bit_ffs
 202  *
 203  * SYNOPSIS
 204  *
 205  *    int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 206  *
 207  * DESCRIPTION
 208  *
 209  *    Returns the bit number of the first set bit in the `bitmap' of size
 210  *    of `bitmap_size'.  Returns -1 on error or when there were no set bits
 211  *    and sets silc_errno.
 212  *
 213  ***/
 214 int silc_bit_ffs(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 215
 216 /****f* silcutil/SilcBitOpAPI/silc_bit_ffz
 217  *
 218  * SYNOPSIS
 219  *
 220  *    int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 221  *
 222  * DESCRIPTION
 223  *
 224  *    Returns the bit number of the first zero bit in the `bitmap' of size
 225  *    of `bitmap_size'.  Returns -1 on error or when there were no zero bits
 226  *    and sets silc_errno.
 227  *
 228  ***/
 229 int silc_bit_ffz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size);
 230
 231 /****f* silcutil/SilcBitOpAPI/silc_bit_fns
 232  *
 233  * SYNOPSIS
 234  *
 235  *    int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 236  *                     SilcUInt32 offset);
 237  *
 238  * DESCRIPTION
 239  *
 240  *    Returns the bit number of the next set bit in the `bitmap' of size
 241  *    of `bitmap_size' starting at bit `offset'.  Returns -1 on error or
 242  *    when there were no more set bits and sets silc_errno.
 243  *
 244  ***/
 245 int silc_bit_fns(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 246                  SilcUInt32 offset);
 247
 248 /****f* silcutil/SilcBitOpAPI/silc_bit_fnz
 249  *
 250  * SYNOPSIS
 251  *
 252  *    int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 253  *                     SilcUInt32 offset);
 254  *
 255  * DESCRIPTION
 256  *
 257  *    Returns the bit number of the next zero bit in the `bitmap' of size
 258  *    of `bitmap_size' starting at bit `offset'.  Returns -1 on error or
 259  *    when there were no more zero bits and sets silc_errno.
 260  *
 261  ***/
 262 int silc_bit_fnz(volatile unsigned long *bitmap, SilcUInt32 bitmap_size,
 263                  SilcUInt32 offset);
 264
 265 /****f* silcutil/SilcBitOpAPI/silc_bit_clear_bitmap
 266  *
 267  * SYNOPSIS
 268  *
 269  *    void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
 270  *                               SilcUInt32 bitmap_size);
 271  *
 272  * DESCRIPTION
 273  *
 274  *    Clears the whole bitmap.
 275  *
 276  ***/
 277 void silc_bit_clear_bitmap(volatile unsigned long *bitmap,
 278                            SilcUInt32 bitmap_size);
 279
 280 #endif /* SILCBITOPS_H */