Adding to the lib a proper pipelining API

[Dolu1990]

Hi,

So, https://github.com/SpinalHDL/SpinalHDL/tree/dev/lib/src/main/scala/spinal/lib/pipeline was added to the lib half a year ago, but i never feeled comfortable enough to set it in stone ( documenting it), as there were quite a few klunky things in it.

I think we can do "Better, Faster, Stronger", cleaner and more flexible
I'm now experimenting with a completly reworked pipelining tool.

Here i'am so far :

    import spinal.lib.misc.pipeline._

    val c0 = CtrlConnector() // Ctrl is a facility which allows to control the flow between 2 nodes (ex halt the flow)
    val c1 = CtrlConnector()
    val c2 = CtrlConnector()

    val s01 = StageConnector(c0.down, c1.up) // RegStage implement a register based connection between 2 nodes (Stream.m2s like)
    val s12 = StageConnector(c1.down, c2.up)

    // Define a thing which can go through the pipeline (this is a typedef used as a key)
    val PC = Stageable(UInt(32 bits))

    val source = slave Stream(PC)
    val sink = master Stream(PC)

    c0.up.driveFrom(source)((self, payload) => self(PC) := payload)
    c1.haltWhen(c1(PC) === 42)
    val PC_PLUS_4 = c1.insert(c1(PC) + 4)
    c2.down.toStream(sink)((payload, self) => payload := self(PC_PLUS_4))

    val connectors = List(c0, c1, c2, s01, s12)
    Builder(connectors)

Got it to generate proper hardware.
So, the main differences with the actual lib.pipeline are :

• we have the definition of Node and Ctrl, while before, it was a totaly coupled thing
• the build function currently allows to have a graph-like pipeline, meaning join / fork. And so for instance for a fork, you would do :
  val myFork = new Fork(a,b,c) //fork a into b/c nodes

This design is much more modular. Note that the above example is a low level example, an lib.pipeline API-like can easily be implemented on the top of it.

Anybody interrested is welcome.

I'm currently playing around this branch :
https://github.com/SpinalHDL/SpinalHDL/tree/composable-exp/lib/src/main/scala/spinal/lib/misc/pipeline

This is to prepare the field of a potential VexiiRiscv

[Dolu1990]

Here are a few simple test cases, in particular to test the CtrlConnector :
https://github.com/SpinalHDL/SpinalHDL/blob/composable-exp/tester/src/test/scala/spinal/lib/misc/pipeline/PipelineTester.scala

[andreasWallner]

Looks very interesting - but I'll have to play a little bit and have a look at it before I can say/ask anything useful...

[RicardoNid]

In my opinion, there are many features in SpinalHDL lib that are closely related to the useful design patterns, such as fsm, Stream|Flow, Bus+RegIf and Pipeline, but the documentation lacks description of their usage scenarios, which makes it difficult for beginners to understand where they use them in their designs.
As for Pipeline, at first I mistakenly thought it could be used in the DSP module, but after looking at the source code in detail, I determined that its semantics were almost entirely designed for the CPU.
In my personal opinion, a clear set of APIs should be accompanied by a simple design case (with slides containing pictures), such as a 2-stage CPU that embodies concepts such as throw and spawn in its pipeline.
In addition, a method of visualizing the stage connection relationships in the Pipeline after elaboration (or at least generating text output) will be of great help to users in learning how to use Pipeline during the trial and error process. In my personal practice for DSP module design (a set of pipeline retiming tools), I host this connection relationship to the graph theory model provided by the jgrapht library, which can avoid me from making errors in the processing of the connection relationship and make visualization easier (currently, I export it into .drawio format, an xml-based vector graphics format), but the cost is to add a JAVA dependency in build.sbt.
Of course, even without using jgrapht, it is not difficult to do visualization from stageSet and connections. In the near future, I will try to add visualization methods to fsm and the current Pipeline, and submit it

[Dolu1990]

I determined that its semantics were almost entirely designed for the CPU.

Yes, i had CPU requirements in mind when designing the API. What are the feature that DSP pipeline would need which are outside the scope of CPU requirements ?

• Eventualy retiming, but that's probably something too tricky
• More join / fork utilities

So, to give an example which is kinda similar to this API but using the lib.pipeline API, i designed the NaxRiscv FPU and the L2 coherent cache with it.
The main advantage i would say is that you do not have to define bundle with your stuff on each stage, instead you use Stageable.
Here is for instance the rounding stages of the FPU (s1,s2,s3) :
https://github.com/SpinalHDL/NaxRiscv/blob/2a498c2a0690c344737094a156a2bf27307cf46d/src/main/scala/naxriscv/execute/fpu/FpuCore.scala#L815
Here is an example in the l2 cache :

SpinalHDL/lib/src/main/scala/spinal/lib/bus/tilelink/coherent/Cache.scala

Line 1107 in 7314a3d

val readBackend = new Pipeline {

[Dolu1990]

Ahhh note about manual retiming, the pipelining API alows to do it in some ways which is realy smooth, note that on :

SpinalHDL/lib/src/main/scala/spinal/lib/bus/tilelink/coherent/Cache.scala

Line 1109 in 7314a3d

val inserterStage = stages(0)

is defined in which stage is done what, so you can easily move things around without chaning any other code.

[Dolu1990]

I just tried to make a more DSP like pipeline, meaning not using the CtrlConnector at all :

    val n0, n1, n2, n3 = new Node()

    val s01 = StageConnector(n0, n1)
    val s12 = StageConnector(n1, n2)
    val s23 = StageConnector(n2, n3)

    val IN = Stageable(UInt(16 bits))
    val OUT = Stageable(UInt(16 bits))
    
    n0(IN) := xxx
    val TMP = n1.insert(n1(IN) + 4)
    n2(OUT) := n2(TMP)+45
    val x = n3(OUT)

It works well :)

[dreamflyings]

The DSP-related git projects and documentation are as follows: https://github.com/Chainsaw-Team/Chainsaw and https://github.com/Chainsaw-Team/ChainsawDoc. His project is a little difficult, and I haven't studied it yet. Based on my previous experience in image processing algorithms, my understanding is that this more generalized pipeline design,Data pipeline and control pipeline may be accompanied; the control pipeline may not be global or segmented; QueueLink (similar to StageLink) is used for transmission of pipeline payload between ctrl pipeline segments; Some control signals are distributed at the source to individual ctrl pipeline segments or data pipelines, just like the Retention Station in the CPU.

[Dolu1990]

Thanks for the links :D
I checked the doc, but it seems only the Scala-doc, not a hand written one ? or i missed a part ?

[Dolu1990]

Added a documentation PR :
SpinalHDL/SpinalDoc-RTD#226

[Dolu1990]

Hi,

There is quite a few feature / doc which were added, i would say it would be ok for merge in dev.

Especialy :

• https://github.com/SpinalHDL/SpinalDoc-RTD/blob/1b8815c33c774eda5fde476b9d7aee8381e9377a/source/SpinalHDL/Libraries/Pipeline/introduction.rst#composability
• https://github.com/SpinalHDL/SpinalDoc-RTD/blob/1b8815c33c774eda5fde476b9d7aee8381e9377a/source/SpinalHDL/Libraries/Pipeline/introduction.rst#retiming--variable-lenth

[Dolu1990]

Maybe one thing left, is to be sure "Stageable" is the right name, maybe it should be something more generic, like HardKey, NamedType or something like it ?