From b68dcaf9245a006bff0d39d922d13a9353e79222 Mon Sep 17 00:00:00 2001
From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Thu, 15 Aug 2019 17:57:05 +0100
Subject: [PATCH] update MaskCancellable docstrings

---
 src/nmutil/singlepipe.py | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/nmutil/singlepipe.py b/src/nmutil/singlepipe.py
index 3a04fbf9..7ffd61c9 100644
--- a/src/nmutil/singlepipe.py
+++ b/src/nmutil/singlepipe.py
@@ -461,7 +461,15 @@ class MaskNoDelayCancellable(ControlBase):
 class MaskCancellable(ControlBase):
     """ Mask-activated Cancellable pipeline
 
-        Argument: stage.  see Stage API above
+        Arguments:
+
+        * stage.  see Stage API above
+        * maskwid - sets up cancellation capability (mask and stop).
+        * in_multi
+        * stage_ctl
+        * dynamic - allows switching from sync to combinatorial (passthrough)
+                    USE WITH CARE.  will need the entire pipe to be quiescent
+                    before switching, otherwise data WILL be destroyed.
 
         stage-1   p.valid_i >>in   stage   n.valid_o out>>   stage+1
         stage-1   p.ready_o <<out  stage   n.ready_i <<in    stage+1
@@ -533,7 +541,8 @@ class MaskCancellable(ControlBase):
 
         with m.Else():
             # pass everything straight through.  p connected to n: data,
-            # valid, mask, everything.
+            # valid, mask, everything.  this is "effectively" just a
+            # StageChain (except now dynamically selectable)
             data_o = self._postprocess(self.data_r)
             m.d.comb += self.n.valid_o.eq(self.p.valid_i_test)
             m.d.comb += self.p._ready_o.eq(self.n.ready_i_test)
@@ -541,7 +550,6 @@ class MaskCancellable(ControlBase):
             m.d.comb += self.n.mask_o.eq(self.p.mask_i)
             m.d.comb += nmoperator.eq(self.n.data_o, data_o)
 
-
         return self.m
 
 
-- 
2.30.2