Dsptools examples #457

ryan-lund · 2020-03-02T19:38:53Z

Adds two examples of accelerators created using dsptools that can be attached to a Rocket Core as MMIOs. The blocks are:

Passthrough (sanity check)
Generic FIR Filter

…pherial

grebe · 2020-03-09T17:16:14Z

generators/example/src/main/scala/ConfigMixins.scala

+  case PassthroughKey => Some(PassthroughParams(depth = 8))
+})
+
+class WithUIntTestFIR extends Config((site, here, up) => {


The example should probably use FixedPoint for the FIR filter.

grebe · 2020-03-09T17:19:44Z

generators/example/src/main/scala/dsptools/GenericFIR.scala

+  io.in.ready := directCells.head.in.ready
+
+  // connect adjacent cells
+  for ((current, next) <- directCells.zip(directCells.tail)) {


This is doing something a little tricky, and the comment should probably reflect that. directCells.tail is one element shorter than directCells, and zip doesn't look at the last element of directCells. Maybe we should call dropRight? I'm not sure what's least confusing. It definitely works as written, but I think it would be good to make the example easy to understand. What do you think?

grebe · 2020-03-09T17:21:09Z

generators/example/src/main/scala/dsptools/Passthrough.scala

+PassthroughBlock[TLClientPortParameters, TLManagerPortParameters, TLEdgeOut, TLEdgeIn, TLBundle, T](proto)
+with TLDspBlock
+
+/**


Let's remove this commented out stuff. I think it actually should work to do this way, but as currently written I think it makes a better example

Should I in this case remove the initial PassthroughChain implementation?

grebe · 2020-03-09T17:21:49Z

generators/example/src/main/scala/dsptools/Passthrough.scala

+  * @param p
+  * @tparam T Type parameter for passthrough, i.e. FixedPoint or DspReal
+  */
+class TLPassthroughThing[T<:Data:Ring](params: PassthroughParams, proto: T)(implicit p: Parameters)


Instead of Thing, let's call it something else. Maybe Chain?

Same as below

grebe · 2020-03-09T17:22:21Z

generators/example/src/main/scala/dsptools/GenericFIR.scala

+    genIn, genOut, coeffs
+) with TLDspBlock
+
+class TLGenericFIRThing[T<:Data:Ring] (genIn: T, genOut: T, coeffs: Seq[T], params: GenericFIRParams)(implicit p: Parameters)


Let's call this something other than Thing, perhaps Chain? MM?

Renamed in latest update (TLGenericFIRChain)

alonamid · 2020-03-09T20:43:46Z

Some initial comments:

I would recommend re-basing this ASAP over the current dev branch (the configs system has changed since PR IOBinders and BuildTop unification between FireChip and Chipyard #390 )
Needs documentation (in within chipyard/docs)
The passthrough name is somewhat confusing. Would recommend renaming it (maybe dsp-passthrough?)

grebe · 2020-03-10T03:48:17Z

Maybe StreamingPassthrough?

…s fixed point

ryan-lund · 2020-03-11T22:08:46Z

Maybe StreamingPassthrough?

As of now I've changed Passthrough to this.

…of Thing to Chain and remove old Chain

…pherial

…s fixed point

…of Thing to Chain and remove old Chain

alonamid · 2020-03-13T00:52:44Z

docs/Customization/Dsptools-Blocks.rst

+Dsptools Blocks
+===============
+
+Another way to create a MMIO peripheral is to use the Dsptools library for Chisel. In this method, a chain is created by placing a custom module inside a ``DspBlock`` and sandwiching that block between a ``ReadQueue`` and ``WriteQueue``. Those queues then act as memory mapped interfaces to the Rocket Chip SoCs. This section will again primarily focuso n designing Tilelink-based peripherals. However, through the resources provided in Dsptools, one could also define an AXI4-based peripheral by following similar steps.


When you say "chain", do you mean a streaming interface?

docs/Customization/Dsptools-Blocks.rst

alonamid · 2020-03-13T00:55:03Z

docs/Customization/Dsptools-Blocks.rst

@@ -0,0 +1,105 @@
+.. _dsptools-blocks:
+
+Dsptools Blocks


There needs to be some introduction here.
What is the main use-case here? (DSP chains....)
What are we trying to do?
Why does this main use-case need a different flow than the standard MMIO method?

alonamid · 2020-03-13T00:56:45Z

docs/Customization/Dsptools-Blocks.rst

+
+Another way to create a MMIO peripheral is to use the Dsptools library for Chisel. In this method, a chain is created by placing a custom module inside a ``DspBlock`` and sandwiching that block between a ``ReadQueue`` and ``WriteQueue``. Those queues then act as memory mapped interfaces to the Rocket Chip SoCs. This section will again primarily focuso n designing Tilelink-based peripherals. However, through the resources provided in Dsptools, one could also define an AXI4-based peripheral by following similar steps.
+
+For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``.


Is there a documentation page somewhere that talks about how to write an FIR filter using Dsptools?

alonamid · 2020-03-13T00:57:36Z

docs/Customization/Dsptools-Blocks.rst

+
+For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``.
+
+We module ``GenericFIR`` links together a variable number of ``GenericFIRDirectCell`` submodules which work togther to perform the filtering. It is important to note that both modules are type generic, which means that they can be instantiated for any datatype that implements ``Ring`` operations per the specifications on ``T``.


Can you clarify the first sentence here?

alonamid · 2020-03-13T01:00:01Z

docs/Customization/Dsptools-Blocks.rst

@@ -0,0 +1,105 @@
+.. _dsptools-blocks:


@grebe , I think there should be some introduction to DSP tools. I know there is some in the dsp-tools README, but I don't think it's sufficient.

This page talks about Ring operations which could use some additional introduction

alonamid · 2020-03-13T01:04:15Z

I would also like to see the documentation page generalized to a general DSP blocks. The FIR walkthrough should still be there, but as an example, rather than a target design. The target audience of this page should be someone writing an arbitrary DSP block (correlator, averaging window, FFT, etc.), and they should be able to understand what is specific to an FIR filter in this example, and what is generally applicable to their DSP block.

Co-Authored-By: alonamid <alonamid@eecs.berkeley.edu>

…ied to a generalized block

…master

Refactoring

alonamid · 2020-04-11T22:50:23Z

generators/chipyard/src/main/scala/example/dsptools/Passthrough.scala

+    def apply[T<:Data:Ring](proto: T): StreamingPassthroughIO[T] = new StreamingPassthroughIO(proto)
+}
+
+class StreamingPassthrough[T<:Data:Ring](proto: T) extends Module {


Update the file name as well to StreamingPassthrough?

alonamid · 2020-04-11T22:51:00Z

tests/Makefile

@@ -5,7 +5,7 @@ LDFLAGS= -static

 include libgloss.mk

-PROGRAMS = pwm blkdev accum charcount nic-loopback big-blkdev pingd
+PROGRAMS = pwm blkdev accum charcount nic-loopback big-blkdev pingd passthrough fir


update the "passthrough" name here as well?

alonamid · 2020-04-11T22:53:27Z

docs/Customization/Dsptools-Blocks.rst

+Dsptools Blocks
+===============
+
+Another way to create a MMIO peripheral is to use the Dsptools library for Chisel. In this method, a memory interface is created by creating a "chain". This chain consists of a custom module placed inside a ``DspBlock``, which is then sandwiched between a ``ReadQueue`` and ``WriteQueue``. Those queues then act as memory mapped interfaces to the Rocket Chip SoCs. This section will again primarily focus on designing Tilelink-based peripherals. However, through the resources provided in Dsptools, one could also define an AXI4-based peripheral by following similar steps.


Can you clarify the difference between adding an MMIO peripheral using this method vs. the "usual" method. In other words: is this a "special case" of the general method, or is this an alternative?

alonamid · 2020-04-11T23:00:30Z

docs/Customization/Dsptools-Blocks.rst

+
+Another way to create a MMIO peripheral is to use the Dsptools library for Chisel. In this method, a memory interface is created by creating a "chain". This chain consists of a custom module placed inside a ``DspBlock``, which is then sandwiched between a ``ReadQueue`` and ``WriteQueue``. Those queues then act as memory mapped interfaces to the Rocket Chip SoCs. This section will again primarily focus on designing Tilelink-based peripherals. However, through the resources provided in Dsptools, one could also define an AXI4-based peripheral by following similar steps.
+
+For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``. That being said, one could substitute any module with a ready valid interface in the place of the FIR and achieve the same results. As long as the read and valid signals of the module are attached to those of a corresponding ``DSPBlock`` wrapper, and that wrapper is placed in a chain with a ``ReadQueue`` and a ``WriteQueue``, following the general outline establised by these steps will allow you to interact with that block as a memory mapped IO


Suggested change

For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``. That being said, one could substitute any module with a ready valid interface in the place of the FIR and achieve the same results. As long as the read and valid signals of the module are attached to those of a corresponding ``DSPBlock`` wrapper, and that wrapper is placed in a chain with a ``ReadQueue`` and a ``WriteQueue``, following the general outline establised by these steps will allow you to interact with that block as a memory mapped IO

For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``. That being said, one could substitute any module with a ready valid interface in the place of the FIR and achieve the same results. As long as the ready and valid signals of the module are attached to those of a corresponding ``DSPBlock`` wrapper, and that wrapper is placed in a chain with a ``ReadQueue`` and a ``WriteQueue``, following the general outline established by these steps will allow you to interact with that block as a memory mapped IO

Also, what would be other good examples of things other than FIR to implement using this method?

alonamid · 2020-04-11T23:01:11Z

docs/Customization/Dsptools-Blocks.rst

+
+For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``. That being said, one could substitute any module with a ready valid interface in the place of the FIR and achieve the same results. As long as the read and valid signals of the module are attached to those of a corresponding ``DSPBlock`` wrapper, and that wrapper is placed in a chain with a ``ReadQueue`` and a ``WriteQueue``, following the general outline establised by these steps will allow you to interact with that block as a memory mapped IO
+
+The module ``GenericFIR`` is the overall wrapper of our FIR module. This module links together a variable number of ``GenericFIRDirectCell`` submodules, each of which performs the computations for one coefficient in a FIR direct form architecture. It is important to note that both modules are type generic, which means that they can be instantiated for any datatype that implements ``Ring`` operations per the specifications on ``T``.


Could you add a diagram to clarify this? Seems like there are at least 3 different layers of wrappers here...

alonamid · 2020-04-11T23:06:58Z

docs/Customization/Dsptools-Blocks.rst

+    :start-after: DOC include start: CanHavePeripheryUIntTestFIR chisel
+    :end-before: DOC include end: CanHavePeripheryUIntTestFIR chisel
+
+Note that this is the point at which we decide the datatype for our FIR. It is also possible with some reworking to push the datatype selection out to the top level.


If you're not going to explain what "reworking" you're talking about, I would just remove that comment

alonamid · 2020-04-11T23:07:46Z

docs/Customization/Dsptools-Blocks.rst

+Testing
+-------
+
+We can now test that the FIR is working. The test program is found in ``tests/gcd.c``.


Suggested change

We can now test that the FIR is working. The test program is found in ``tests/gcd.c``.

We can now test that the FIR is working. The test program is found in ``tests/fir.c``.

alonamid · 2020-04-11T23:09:00Z

docs/Customization/index.rst

@@ -11,7 +11,9 @@ These guides will walk you through customization of your system-on-chip:

 - Adding custom MMIO widgets to the Chipyard memory system by Tilelink or AXI4, with custom Top-level IOs

- Standard practices for using keys, traits, and configs to parameterize your design
+- Adding custom Dsptools based blocks as MMIO widgets.


I would consider putting this in a different place, since it is in fact a "special case" of the previous section

alonamid · 2020-04-11T23:12:44Z

generators/chipyard/src/main/scala/config/RocketConfigs.scala

+
+class UIntStreamingPassthroughRocketConfig extends Config(
+  new chipyard.example.WithUIntStreamingPassthrough ++     // use top with tilelink-controlled passthrough
+  new RocketConfig


Our current approach is to use explicit expanded configs rather than this inherited one (see every other config in this file)

alonamid · 2020-04-11T23:12:53Z

generators/chipyard/src/main/scala/config/RocketConfigs.scala

+// DOC include start: FIRRocketConfig
+class UIntTestFIRRocketConfig extends Config (
+  new chipyard.example.WithUIntTestFIR ++ // use top with tilelink-controlled FIR
+  new RocketConfig


Our current approach is to use explicit expanded configs rather than this inherited one (see every other config in this file)

alonamid · 2020-04-11T23:13:04Z

A few additional comments:

@grebe , at some point, can you PR this into a branch within the chipyard repo (not dev), and then open a new PR to dev so CI will run?
For consistency sake, make sure passthrough is replaced with streaming-passthrough everywhere (including file names, C files, documentation, etc.)
Maybe talk about the streaming-passthrough example in the documentation as well?
From a documentation and organization perspective, is this a "special case" of an MMIO peripheral, or an alternative? We've been describing RoCC and MMIO as a pseudo "dichotomy" for custom blocks, and I think it's worth clarifying where do these dsptools examples fit in this world. I believe you're trying to put an emphasis on streaming chains, but I'm not sure this idea is conveyed well enough. If this is a special case of MMIO, I would prefer to put perhaps put it as a subsection of the general MMIO explanation, or clarify that this is essentially another example of the same method.
Add a CI test for dsptools

lpppeipei · 2022-01-10T12:25:15Z

I would also like to see the documentation page generalized to a general DSP blocks. The FIR walkthrough should still be there, but as an example, rather than a target design. The target audience of this page should be someone writing an arbitrary DSP block (correlator, averaging window, FFT, etc.), and they should be able to understand what is specific to an FIR filter in this example, and what is generally applicable to their DSP block.

About " The target audience of this page should be someone writing an arbitrary DSP block (correlator, averaging window, FFT, etc.)", now I would like to write a FFT DSP Block , is there some information for me? Thanks a lot !

Ryan Lund added 7 commits February 18, 2020 09:35

Add c test files for DSPTools example

c170582

Update tests Makefile to build DSPTools c tests

f71e29a

Add DSPTools example configs to ConfigMixins and RocketConfigs

50bc946

Add dsptools and rocket-dsptools as dependancies for example

f0c27a9

Add Scala implementations of DSPTools test blocks

b5da0c3

Clean up GenericFIR scala

a9465fe

Modify dsptools blocks and mixins to match 'CanHave' when adding peri…

c9bd2ef

…pherial

alonamid requested review from grebe and alonamid March 7, 2020 01:10

grebe requested changes Mar 9, 2020

View reviewed changes

Update documentation, will need reworking once FIR is characterized a…

5c68db6

…s fixed point

Ryan Lund and others added 11 commits March 11, 2020 15:09

Update naming of Passthrough to Streaming Passthrough. Update naming …

ff445fc

…of Thing to Chain and remove old Chain

Fix capitalization in docs (#419)

f216ca3

Add c test files for DSPTools example

e840dcb

Update tests Makefile to build DSPTools c tests

b99aeae

Add DSPTools example configs to ConfigMixins and RocketConfigs

b303953

Add dsptools and rocket-dsptools as dependancies for example

393ed86

Add Scala implementations of DSPTools test blocks

5888ada

Clean up GenericFIR scala

a5d95f8

Modify dsptools blocks and mixins to match 'CanHave' when adding peri…

768f1ca

…pherial

Update documentation, will need reworking once FIR is characterized a…

2a79e6d

…s fixed point

Update naming of Passthrough to Streaming Passthrough. Update naming …

dd2c00a

…of Thing to Chain and remove old Chain

alonamid reviewed Mar 13, 2020

View reviewed changes

docs/Customization/Dsptools-Blocks.rst Outdated Show resolved Hide resolved

alonamid reviewed Mar 13, 2020

View reviewed changes

ryan-lund and others added 3 commits March 18, 2020 18:04

Update docs/Customization/Dsptools-Blocks.rst

acd0596

Co-Authored-By: alonamid <alonamid@eecs.berkeley.edu>

Docummentation update for clarity and to explain how this can be appl…

c85a225

…ied to a generalized block

Merge branch 'master' of https://github.com/ryan-lund/chipyard

4807b86

abejgonzalez added the docs label Mar 19, 2020

grebe and others added 5 commits March 30, 2020 17:27

Merge branch 'master' of https://github.com/ryan-lund/chipyard into r…

1678b4b

…master

Merge remote-tracking branch 'origin/dev' into rmaster

4ad7acd

Some refactoring to get dsptools working with these examples

0a88bf5

Oops, old files crept in

60d2446

Merge pull request #1 from grebe/refactoring

f25a10a

Refactoring

alonamid reviewed Apr 11, 2020

View reviewed changes

ryan-lund changed the base branch from dev to dev-dsptools April 16, 2020 19:39

grebe merged commit 35cba5d into ucb-bar:dev-dsptools Apr 20, 2020

alonamid mentioned this pull request May 30, 2020

Chipyard 1.3 Release #500

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Dsptools examples #457

Dsptools examples #457

ryan-lund commented Mar 2, 2020

grebe Mar 9, 2020

grebe Mar 9, 2020

grebe Mar 9, 2020

ryan-lund Mar 11, 2020

grebe Mar 9, 2020

ryan-lund Mar 11, 2020

grebe Mar 9, 2020

ryan-lund Mar 11, 2020

alonamid commented Mar 9, 2020

grebe commented Mar 10, 2020

ryan-lund commented Mar 11, 2020

alonamid Mar 13, 2020

alonamid Mar 13, 2020 •

edited

Loading

alonamid Mar 13, 2020

alonamid Mar 13, 2020

alonamid Mar 13, 2020

alonamid commented Mar 13, 2020

alonamid Apr 11, 2020

alonamid Apr 11, 2020

alonamid Apr 11, 2020

alonamid Apr 11, 2020

alonamid Apr 11, 2020

alonamid Apr 11, 2020 •

edited

Loading

alonamid Apr 11, 2020

alonamid Apr 11, 2020

alonamid Apr 11, 2020

alonamid Apr 11, 2020

alonamid Apr 11, 2020

alonamid commented Apr 11, 2020

lpppeipei commented Jan 10, 2022


		Another way to create a MMIO peripheral is to use the Dsptools library for Chisel. In this method, a chain is created by placing a custom module inside a ``DspBlock`` and sandwiching that block between a ``ReadQueue`` and ``WriteQueue``. Those queues then act as memory mapped interfaces to the Rocket Chip SoCs. This section will again primarily focuso n designing Tilelink-based peripherals. However, through the resources provided in Dsptools, one could also define an AXI4-based peripheral by following similar steps.

		For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``.


		For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``.

		We module ``GenericFIR`` links together a variable number of ``GenericFIRDirectCell`` submodules which work togther to perform the filtering. It is important to note that both modules are type generic, which means that they can be instantiated for any datatype that implements ``Ring`` operations per the specifications on ``T``.


		For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``. That being said, one could substitute any module with a ready valid interface in the place of the FIR and achieve the same results. As long as the read and valid signals of the module are attached to those of a corresponding ``DSPBlock`` wrapper, and that wrapper is placed in a chain with a ``ReadQueue`` and a ``WriteQueue``, following the general outline establised by these steps will allow you to interact with that block as a memory mapped IO

		The module ``GenericFIR`` is the overall wrapper of our FIR module. This module links together a variable number of ``GenericFIRDirectCell`` submodules, each of which performs the computations for one coefficient in a FIR direct form architecture. It is important to note that both modules are type generic, which means that they can be instantiated for any datatype that implements ``Ring`` operations per the specifications on ``T``.

	We can now test that the FIR is working. The test program is found in ``tests/gcd.c``.
	We can now test that the FIR is working. The test program is found in ``tests/fir.c``.

Dsptools examples #457

Dsptools examples #457

Conversation

ryan-lund commented Mar 2, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alonamid commented Mar 9, 2020

grebe commented Mar 10, 2020

ryan-lund commented Mar 11, 2020

Choose a reason for hiding this comment

alonamid Mar 13, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alonamid commented Mar 13, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alonamid Apr 11, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alonamid commented Apr 11, 2020

lpppeipei commented Jan 10, 2022

alonamid Mar 13, 2020 •

edited

Loading

alonamid Apr 11, 2020 •

edited

Loading