lib/axmap: Add more documentation
[fio.git] / lib / axmap.c
index 454af0b9d0361806bbf515c2e9c5c94776db3891..4a907fec22d2f8a2723121d8236d7a56be6db01c 100644 (file)
@@ -35,8 +35,6 @@
 #define BLOCKS_PER_UNIT                (1U << UNIT_SHIFT)
 #define BLOCKS_PER_UNIT_MASK   (BLOCKS_PER_UNIT - 1)
 
-#define firstfree_valid(b)     ((b)->first_free != (uint64_t) -1)
-
 static const unsigned long bit_masks[] = {
        0x0000000000000000, 0x0000000000000001, 0x0000000000000003, 0x0000000000000007,
        0x000000000000000f, 0x000000000000001f, 0x000000000000003f, 0x000000000000007f,
@@ -59,16 +57,29 @@ static const unsigned long bit_masks[] = {
 #endif
 };
 
+/**
+ * struct axmap_level - a bitmap used to implement struct axmap
+ * @level: Level index. Each map has at least one level with index zero. The
+ *     higher the level index, the fewer bits a struct axmap_level contains.
+ * @map_size: Number of elements of the @map array.
+ * @map: A bitmap with @map_size elements.
+ */
 struct axmap_level {
        int level;
        unsigned long map_size;
        unsigned long *map;
 };
 
+/**
+ * struct axmap - a set that can store numbers 0 .. @nr_bits - 1
+ * @nr_level: Number of elements of the @levels array.
+ * @levels: struct axmap_level array in which lower levels contain more bits
+ *     than higher levels.
+ * @nr_bits: One more than the highest value stored in the set.
+ */
 struct axmap {
        unsigned int nr_levels;
        struct axmap_level *levels;
-       uint64_t first_free;
        uint64_t nr_bits;
 };
 
@@ -80,6 +91,7 @@ static inline unsigned long ulog64(unsigned long val, unsigned int log)
        return val;
 }
 
+/* Remove all elements from the @axmap set */
 void axmap_reset(struct axmap *axmap)
 {
        int i;
@@ -89,8 +101,6 @@ void axmap_reset(struct axmap *axmap)
 
                memset(al->map, 0, al->map_size * sizeof(unsigned long));
        }
-
-       axmap->first_free = 0;
 }
 
 void axmap_free(struct axmap *axmap)
@@ -107,6 +117,7 @@ void axmap_free(struct axmap *axmap)
        free(axmap);
 }
 
+/* Allocate memory for a set that can store the numbers 0 .. @nr_bits - 1. */
 struct axmap *axmap_new(unsigned long nr_bits)
 {
        struct axmap *axmap;
@@ -151,6 +162,11 @@ err:
        return NULL;
 }
 
+/*
+ * Call @func for each level, starting at level zero, until a level is found
+ * for which @func returns true. Return false if none of the @func calls
+ * returns true.
+ */
 static bool axmap_handler(struct axmap *axmap, uint64_t bit_nr,
                          bool (*func)(struct axmap_level *, unsigned long, unsigned int,
                          void *), void *data)
@@ -175,6 +191,11 @@ static bool axmap_handler(struct axmap *axmap, uint64_t bit_nr,
        return false;
 }
 
+/*
+ * Call @func for each level, starting at the highest level, until a level is
+ * found for which @func returns true. Return false if none of the @func calls
+ * returns true.
+ */
 static bool axmap_handler_topdown(struct axmap *axmap, uint64_t bit_nr,
        bool (*func)(struct axmap_level *, unsigned long, unsigned int, void *))
 {
@@ -192,29 +213,16 @@ static bool axmap_handler_topdown(struct axmap *axmap, uint64_t bit_nr,
        return false;
 }
 
-static bool axmap_clear_fn(struct axmap_level *al, unsigned long offset,
-                          unsigned int bit, void *unused)
-{
-       if (!(al->map[offset] & (1UL << bit)))
-               return true;
-
-       al->map[offset] &= ~(1UL << bit);
-       return false;
-}
-
-void axmap_clear(struct axmap *axmap, uint64_t bit_nr)
-{
-       axmap_handler(axmap, bit_nr, axmap_clear_fn, NULL);
-
-       if (bit_nr < axmap->first_free)
-               axmap->first_free = bit_nr;
-}
-
 struct axmap_set_data {
        unsigned int nr_bits;
        unsigned int set_bits;
 };
 
+/*
+ * Set at most @__data->nr_bits bits in @al at offset @offset. Do not exceed
+ * the boundary of the element at offset @offset. Return the number of bits
+ * that have been set in @__data->set_bits if @al->level == 0.
+ */
 static bool axmap_set_fn(struct axmap_level *al, unsigned long offset,
                         unsigned int bit, void *__data)
 {
@@ -253,19 +261,25 @@ done:
        if (!al->level)
                data->set_bits = nr_bits;
 
+       /* For the next level */
        data->nr_bits = 1;
+
        return al->map[offset] != -1UL;
 }
 
+/*
+ * Set up to @data->nr_bits starting from @bit_nr in @axmap. Start at
+ * @bit_nr. If that bit has not yet been set then set it and continue until
+ * either @data->nr_bits have been set or a 1 bit is found. Store the number
+ * of bits that have been set in @data->set_bits. It is guaranteed that all
+ * bits that have been requested to set fit in the same unsigned long word of
+ * level 0 of @axmap.
+ */
 static void __axmap_set(struct axmap *axmap, uint64_t bit_nr,
                         struct axmap_set_data *data)
 {
        unsigned int set_bits, nr_bits = data->nr_bits;
 
-       if (axmap->first_free >= bit_nr &&
-           axmap->first_free < bit_nr + data->nr_bits)
-               axmap->first_free = -1ULL;
-
        if (bit_nr > axmap->nr_bits)
                return;
        else if (bit_nr + nr_bits > axmap->nr_bits)
@@ -296,6 +310,12 @@ void axmap_set(struct axmap *axmap, uint64_t bit_nr)
        __axmap_set(axmap, bit_nr, &data);
 }
 
+/*
+ * Set up to @nr_bits starting from @bit in @axmap. Start at @bit. If that
+ * bit has not yet been set then set it and continue until either @nr_bits
+ * have been set or a 1 bit is found. Return the number of bits that have been
+ * set.
+ */
 unsigned int axmap_set_nr(struct axmap *axmap, uint64_t bit_nr,
                          unsigned int nr_bits)
 {
@@ -336,99 +356,119 @@ bool axmap_isset(struct axmap *axmap, uint64_t bit_nr)
        return false;
 }
 
-static uint64_t axmap_find_first_free(struct axmap *axmap, unsigned int level,
-                                      uint64_t index)
+/*
+ * Find the first free bit that is at least as large as bit_nr.  Return
+ * -1 if no free bit is found before the end of the map.
+ */
+static uint64_t axmap_find_first_free(struct axmap *axmap, uint64_t bit_nr)
 {
-       uint64_t ret = -1ULL;
-       unsigned long j;
        int i;
+       unsigned long temp;
+       unsigned int bit;
+       uint64_t offset, base_index, index;
+       struct axmap_level *al;
 
-       /*
-        * Start at the bottom, then converge towards first free bit at the top
-        */
-       for (i = level; i >= 0; i--) {
-               struct axmap_level *al = &axmap->levels[i];
-
-               if (index >= al->map_size)
-                       goto err;
-
-               for (j = index; j < al->map_size; j++) {
-                       if (al->map[j] == -1UL)
-                               continue;
+       index = 0;
+       for (i = axmap->nr_levels - 1; i >= 0; i--) {
+               al = &axmap->levels[i];
 
-                       /*
-                        * First free bit here is our index into the first
-                        * free bit at the next higher level
-                        */
-                       ret = index = (j << UNIT_SHIFT) + ffz(al->map[j]);
-                       break;
+               /* Shift previously calculated index for next level */
+               index <<= UNIT_SHIFT;
+
+               /*
+                * Start from an index that's at least as large as the
+                * originally passed in bit number.
+                */
+               base_index = bit_nr >> (UNIT_SHIFT * i);
+               if (index < base_index)
+                       index = base_index;
+
+               /* Get the offset and bit for this level */
+               offset = index >> UNIT_SHIFT;
+               bit = index & BLOCKS_PER_UNIT_MASK;
+
+               /*
+                * If the previous level had unused bits in its last
+                * word, the offset could be bigger than the map at
+                * this level. That means no free bits exist before the
+                * end of the map, so return -1.
+                */
+               if (offset >= al->map_size)
+                       return -1ULL;
+
+               /* Check the first word starting with the specific bit */
+               temp = ~bit_masks[bit] & ~al->map[offset];
+               if (temp)
+                       goto found;
+
+               /*
+                * No free bit in the first word, so iterate
+                * looking for a word with one or more free bits.
+                */
+               for (offset++; offset < al->map_size; offset++) {
+                       temp = ~al->map[offset];
+                       if (temp)
+                               goto found;
                }
-       }
 
-       if (ret < axmap->nr_bits)
-               return ret;
+               /* Did not find a free bit */
+               return -1ULL;
 
-err:
-       return (uint64_t) -1ULL;
-}
-
-static uint64_t axmap_first_free(struct axmap *axmap)
-{
-       if (!firstfree_valid(axmap))
-               axmap->first_free = axmap_find_first_free(axmap, axmap->nr_levels - 1, 0);
-
-       return axmap->first_free;
-}
-
-struct axmap_next_free_data {
-       unsigned int level;
-       unsigned long offset;
-       uint64_t bit;
-};
-
-static bool axmap_next_free_fn(struct axmap_level *al, unsigned long offset,
-                              unsigned int bit, void *__data)
-{
-       struct axmap_next_free_data *data = __data;
-       uint64_t mask = ~bit_masks[(data->bit + 1) & BLOCKS_PER_UNIT_MASK];
-
-       if (!(mask & ~al->map[offset]))
-               return false;
-
-       if (al->map[offset] != -1UL) {
-               data->level = al->level;
-               data->offset = offset;
-               return true;
+found:
+               /* Compute the index of the free bit just found */
+               index = (offset << UNIT_SHIFT) + ffz(~temp);
        }
 
-       data->bit = (data->bit + BLOCKS_PER_UNIT - 1) / BLOCKS_PER_UNIT;
-       return false;
+       /* If found an unused bit in the last word of level 0, return -1 */
+       if (index >= axmap->nr_bits)
+               return -1ULL;
+
+       return index;
 }
 
 /*
  * 'bit_nr' is already set. Find the next free bit after this one.
+ * Return -1 if no free bits found.
  */
 uint64_t axmap_next_free(struct axmap *axmap, uint64_t bit_nr)
 {
-       struct axmap_next_free_data data = { .level = -1U, .bit = bit_nr, };
        uint64_t ret;
+       uint64_t next_bit = bit_nr + 1;
+       unsigned long temp;
+       uint64_t offset;
+       unsigned int bit;
 
-       if (firstfree_valid(axmap) && bit_nr < axmap->first_free)
-               return axmap->first_free;
+       if (bit_nr >= axmap->nr_bits)
+               return -1ULL;
 
-       if (!axmap_handler(axmap, bit_nr, axmap_next_free_fn, &data))
-               return axmap_first_free(axmap);
+       /* If at the end of the map, wrap-around */
+       if (next_bit == axmap->nr_bits)
+               next_bit = 0;
 
-       assert(data.level != -1U);
+       offset = next_bit >> UNIT_SHIFT;
+       bit = next_bit & BLOCKS_PER_UNIT_MASK;
 
        /*
-        * In the rare case that the map is unaligned, we might end up
-        * finding an offset that's beyond the valid end. For that case,
-        * find the first free one, the map is practically full.
+        * As an optimization, do a quick check for a free bit
+        * in the current word at level 0. If not found, do
+        * a topdown search.
         */
-       ret = axmap_find_first_free(axmap, data.level, data.offset);
-       if (ret != -1ULL)
-               return ret;
+       temp = ~bit_masks[bit] & ~axmap->levels[0].map[offset];
+       if (temp) {
+               ret = (offset << UNIT_SHIFT) + ffz(~temp);
 
-       return axmap_first_free(axmap);
+               /* Might have found an unused bit at level 0 */
+               if (ret >= axmap->nr_bits)
+                       ret = -1ULL;
+       } else
+               ret = axmap_find_first_free(axmap, next_bit);
+
+       /*
+        * If there are no free bits starting at next_bit and going
+        * to the end of the map, wrap around by searching again
+        * starting at bit 0.
+        */
+       if (ret == -1ULL && next_bit != 0)
+               ret = axmap_find_first_free(axmap, 0);
+       return ret;
 }