[Patch 1/23] mask v2 - Document bitmap.c bit model

Paul Jackson
2004-04-01T21:29:27Z

Patch_1_of_23 - Document bitmap.c bit model.
Document the bitmap bit model, including handling of unused bits,
and operation preconditions and postconditions.

Diffstat Patch_1_of_23:
bitmap.c | 38 ++++++++++++++++++++++++++++++++++++++
1 files changed, 38 insertions(+)

===================================================================
--- 2.6.4.orig/lib/bitmap.c 2004-03-31 20:47:58.000000000 -0800
+++ 2.6.4/lib/bitmap.c 2004-03-31 21:20:02.000000000 -0800
@@ -12,6 +12,44 @@
#include <asm/bitops.h>
#include <asm/uaccess.h>

+/*
+ * The bitmap bit model:
+ *
+ * The operations in this lib/bitmap.c, and the associated
+ * files include/linux/bitmap.h, include/linux/bitops.h,
+ * and include/asm-*/bitops.h, and in the *_BITMAP macros in
+ * include/linux/types.h, support a model of a set of bits, in
+ * positions 0 .. nbits-1, for some nbits size between 1 and some
+ * modest size. There is no specific limit on the size, but the
+ * internal representation, as an array of unsigned longs, would
+ * not be efficient for very large or sparse sets.
+ *
+ * If the number of valid bits in a particular bitmap is not
+ * an exact multiple of the number of bits in an unsigned long
+ * (BITS_PER_LONG), then there will be some unused bits, in a
+ * so called "tail", that is physically present in the internal
+ * representation, but will appear as if always zero to callers.
+ *
+ * To a first approximation, the "tail" bits are don't care bits.
+ * That is, regardless of their internal state, zero (0) or one
+ * (1), any of these functions will behave as if they were zero.
+ * In particular, all the bitmap functions returning a Boolean
+ * (e.g. bitmap_empty) or scalar (e.g. bitmap_weight) value are
+ * implemented so as to filter out or avoid being affected by
+ * possible one bits in the tail.
+ *
+ * Bitmaps are declared using the DECLARE_BITMAP() macro in
+ * include/linux/types.h. Subsequent operations on a bitmap that
+ * take a bit position, such as set_bit(), must only be provided
+ * positions between 0 and the bitmap size, as first provided
+ * in the DECLARE_BITMAP() invocation. Bitmap operations, such
+ * as bitmap_empty(), that take an argument specifying how many
+ * bits are in the bitmap, must be provided the same number as
+ * first provided to DECLARE_BITMAP(). Bitmap operations such as
+ * bitmap_or() that take two bitmaps as input must be passed two
+ * bitmaps of the same size.
+ */
+
#define MAX_BITMAP_BITS 512U /* for ia64 NR_CPUS maximum */

int bitmap_empty(const unsigned long *bitmap, int bits)