From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Tue, 16 Jun 2020 11:15:42 +0000 (+0100)
Subject: update popcount docstring
X-Git-Tag: div_pipeline~366
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=0c808e017b4349c01354853de3d559c9cf9c8b57;p=soc.git

update popcount docstring
---

diff --git a/src/soc/fu/logical/popcount.py b/src/soc/fu/logical/popcount.py
index e2a28207..23c0ab63 100644
--- a/src/soc/fu/logical/popcount.py
+++ b/src/soc/fu/logical/popcount.py
@@ -1,6 +1,15 @@
-# Popcount: a successive (cascading) sum-reduction algorithm starting from
-# single-bit adds and reducing down to one final answer: the total number of
-# bits set to "1" in the input.
+"""Popcount: a successive (cascading) sum-reduction algorithm for counting bits
+
+starting from single-bit adds and reducing down to one final answer:
+the total number of bits set to "1" in the input.
+
+unfortunately there is a bit of a "trick" going on which you have to
+watch out for: whilst the first list added to pc is a single entry (the
+input, a), subsequent rows in the cascade are arrays of partial results,
+yet it turns out that referring to them using the exact same start/end
+slicing is perfect.  this comes down to nmigen's transparent use of
+python features to make Signals iterable.
+"""
 
 from nmigen import (Elaboratable, Module, Signal, Cat, Const)