On Thu, Feb 29, 2024 at 03:15:51PM +0100, Herve Codina wrote:

From: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

These helpers scatters or gathers a bitmap with the help of the mask
position bits parameter.

bitmap_scatter() does the following:
  src:  0000000001011010
                  ||||||
           +------+|||||
           |  +----+||||
           |  |+----+|||
           |  ||   +-+||
           |  ||   |  ||
  mask: ...v..vv...v..vv
        ...0..11...0..10
  dst:  0000001100000010

and bitmap_gather() performs this one:
   mask: ...v..vv...v..vv
   src:  0000001100000010
            ^  ^^   ^   0
            |  ||   |  10
            |  ||   > 010
            |  |+--> 1010
            |  +--> 11010
            +----> 011010
   dst:  0000000000011010

bitmap_gather() can the seen as the reverse bitmap_scatter() operation.

The original work was done by Andy Shevchenko.

As I said, it's too much credit :-)

...

+ * A relationship exists between bitmap_gather() and bitmap_scatter(). See
+ * bitmap_scatter() for the bitmap scatter detailed operations.
+ * Suppose scattered computed using bitmap_scatter(scattered, src, mask, n).
+ * The operation bitmap_gather(result, scattered, mask, n) leads to a result
+ * equal or equivalent to src.
+ *
+ * The result can be 'equivalent' because bitmap_scatter() and bitmap_gather()
+ * are not bijective.
+ * The result and src values are equivalent in that sense that a call to

+ * bitmap_scatter(res, src, mask, n) and a call to bitmap_scatter(res, result,
+ * mask, n) will lead to the same res value.

For better readability I wouldn't break API calls, hence

 The result and src values are equivalent in that sense that a call to
 bitmap_scatter(res, src, mask, n) and a call to
 bitmap_scatter(res, result, mask, n) will lead to the same res value.

-- 
With Best Regards,
Andy Shevchenko