[Mesa-dev] [PATCH] squash: Add more comments to bitfield manipulations in UBO analysis pass

[Kenneth Graunke]

---
 src/intel/compiler/brw_nir_analyze_ubo_ranges.c | 28 ++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/intel/compiler/brw_nir_analyze_ubo_ranges.c b/src/intel/compiler/brw_nir_analyze_ubo_ranges.c
index 3535e67758c..b365728e77b 100644
--- a/src/intel/compiler/brw_nir_analyze_ubo_ranges.c
+++ b/src/intel/compiler/brw_nir_analyze_ubo_ranges.c
@@ -83,6 +83,10 @@ cmp_ubo_range_entry(const void *va, const void *vb)
 
 struct ubo_block_info
 {
+   /* Each bit in the offsets bitfield represents a 32-byte section of data.
+    * If it's set to one, there is interesting UBO data at that offset.  If
+    * not, there's a "hole" - padding between data - or just nothing at all.
+    */
    uint64_t offsets;
    uint8_t uses[64];
 };
@@ -189,7 +193,7 @@ brw_nir_analyze_ubo_ranges(const struct brw_compiler *compiler,
       }
    }
 
-   /* Find ranges. */
+   /* Find ranges: a block, starting 32-byte offset, and length. */
    struct util_dynarray ranges;
    util_dynarray_init(&ranges, mem_ctx);
 
@@ -199,13 +203,34 @@ brw_nir_analyze_ubo_ranges(const struct brw_compiler *compiler,
       const struct ubo_block_info *info = entry->data;
       uint64_t offsets = info->offsets;
 
+      /* Walk through the offsets bitfield, finding contiguous regions of
+       * set bits:
+       *
+       *   0000000001111111111111000000000000111111111111110000000011111100
+       *            ^^^^^^^^^^^^^            ^^^^^^^^^^^^^^        ^^^^^^
+       *
+       * Each of these will become a UBO range.
+       */
       while (offsets != 0) {
+         /* Find the first 1 in the offsets bitfield.  This represents the
+          * start of a range of interesting UBO data.  Make it zero-indexed.
+          */
          int first_bit = ffsll(offsets) - 1;
+
+         /* Find the first 0 bit in offsets beyond first_bit.  To find the
+          * first zero bit, we find the first 1 bit in the complement.  In
+          * order to ignore bits before first_bit, we mask off those bits.
+          */
          int first_hole = ffsll(~offsets & ~((1ull << first_bit) - 1)) - 1;
+
          if (first_hole == -1) {
+            /* If we didn't find a hole, then set it to the end of the
+             * bitfield.  There are no more ranges to process.
+             */
             first_hole = 64;
             offsets = 0;
          } else {
+            /* We've processed all bits before first_hole.  Mask them off. */
             offsets &= ~((1ull << first_hole) - 1);
          }
 
@@ -214,6 +239,7 @@ brw_nir_analyze_ubo_ranges(const struct brw_compiler *compiler,
 
          entry->range.block = b;
          entry->range.start = first_bit;
+         /* first_hole is one beyond the end, so we don't need to add 1 */
          entry->range.length = first_hole - first_bit;
          entry->benefit = 0;
 
-- 
2.13.2