From d8af5f55d1043c36ed6296c49ed0a9c12cda8c10 Mon Sep 17 00:00:00 2001
From: DEFAULTTEXHAPb <71003801+DEFAULTTEXHAPb@users.noreply.github.com>
Date: Thu, 16 Mar 2023 08:27:30 +0000
Subject: [PATCH] Add StreamTransactionExtender documentation

---
 source/SpinalHDL/Libraries/stream.rst | 56 +++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/source/SpinalHDL/Libraries/stream.rst b/source/SpinalHDL/Libraries/stream.rst
index 4503402e28..6b7c6f58e1 100644
--- a/source/SpinalHDL/Libraries/stream.rst
+++ b/source/SpinalHDL/Libraries/stream.rst
@@ -534,6 +534,62 @@ This util take its input stream and routes it to ``outputCount`` stream in a seq
      outputCount = 3
    )
 
+
+StreamTransactionExtender
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This util take its input stream and insert ``count`` additional samples between input stream samples with rule, defined by function ``driver: (a: UInt, b: T, c: Bool) => x: T2``.
+Where:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 1 1 3
+
+   * - Parameter
+     - Type
+     - Description
+   * - ``a``
+     - ``UInt``
+     - Stream Transaction Counter value. Counter runs in range 0 to ``count-1``
+   * - ``b``
+     - ``T``
+     - Input Stream sample value
+   * - ``c``
+     - ``Bool``
+     - Stream Transaction Counter overflow condition
+
+.. list-table:: StreamTransactionExtender parameters
+   :header-rows: 1
+   :widths: 1 1 3
+
+   * - Parameter
+     - Type
+     - Description
+   * - ``input``
+     - ``Stream[T]``
+     - Input Stream
+   * - ``output``
+     - ``Stream[T2]``
+     - Output Stream with inserted samples
+   * - ``count``
+     - ``UInt``
+     - Number of samples to insert between input stream samples
+
+.. note:: Example:
+
+To implement simple stream upsampler for DSP purposes that insert ``resamplingRate - 1`` zeros between samples of ``sourceStream`` and translate it to ``sinkStream`` it's enough to write following code
+
+.. code-block:: scala
+
+  StreamTransactionExtender(input = sourceStream, output = sinkStream, count = resamplingRate - 1) { (_, p, zero) =>
+    val retVal: T = dataType()
+    retVal.assignFromBits(B(0, dataType.getBitsWidth bits))
+    when(zero) {
+      retVal := p
+    }
+    retVal
+  }  
+
 Simulation support
 ------------------