chisel
chisel copied to clipboard
chipsalliance
Documentation for := vs <>
Contributor Checklist
- [x] Did you add Scaladoc to every public function/method?
- [x] Did you add at least one test demonstrating the PR?
- [x] Did you delete any extraneous printlns/debugging code?
- [x] Did you specify the type of improvement?
- [x] Did you add appropriate documentation in
docs/src? - [x] Did you state the API impact?
- [x] Did you specify the code generation impact?
- [x] Did you request a desired merge strategy?
- [x] Did you add text to be included in the Release Notes for this change?
Type of Improvement
Documentation
API Impact
Add to the existing API No Impact
Backend Code Generation Impact
No Change
Desired Merge Strategy
Squash
Release Notes
Reviewer Checklist (only modified by reviewer)
- [ ] Did you add the appropriate labels?
- [ ] Did you mark the proper milestone (Bug fix:
3.3.x, [small] API extension:3.4.x, API modification or big change:3.5.0)? - [ ] Did you review?
- [ ] Did you check whether all relevant Contributor checkboxes have been checked?
- [ ] Did you mark as
Please Merge?
Since we're still working on this, I am going to move this to DRAFT until we've done some of the experiments.
This is a great first step, I think the next step would be to say, "What if we change this <> to a := ?" and show the resulting verilog. "What if we swap the order of the <> here?" and you can show the error message with scala mdoc:crash
As a heads up, my company is having a long weekend, so many of us will be less active online until next Tuesday.
@mwachs5 Thank you for your help. I will get right to setting up the environment
Hi @mwachs5, I have been trying to get my environment working, I installed sbt, java but got stuck Installing and loading verilator since the commands keep bringing out error. so, I am wondering if Visual code can produce the verilog if the extensions are downloaded on it? if no, should I post the errors I got for you to take a look at it?
You don’t need verilator to generate the verilog or the documentation. The command “sbt docs/mdoc” should work without it
Hi @mwachs5, I ran sbt docs/mdoc. here is the error I got.
[info] started sbt server sbt:chisel3> sbt docs/mdoc [error] Expected ID character [error] Not a valid command: sbt (similar: set, boot, last) [error] Expected 'sbtRebootNetwork' [error] Expected project ID [error] Expected configuration [error] Expected ':' [error] Expected key [error] Not a valid key: sbt (similar: test, state, ivySbt) [error] Expected 'sbtPromptChannel' [error] Expected 'sbtRebootImpl' [error] Expected 'sbtReportResult' [error] Expected 'sbtMapExec' [error] Expected 'sbtCompleteExec' [error] sbt docs/mdoc [error] ^ sbt:chisel3>
Hi @mwachs5, I ran sbt docs/mdoc. here is the error I got.
[info] started sbt server sbt:chisel3> sbt docs/mdoc [error] Expected ID character [error] Not a valid command: sbt (similar: set, boot, last) [error] Expected 'sbtRebootNetwork' [error] Expected project ID [error] Expected configuration [error] Expected ':' [error] Expected key [error] Not a valid key: sbt (similar: test, state, ivySbt) [error] Expected 'sbtPromptChannel' [error] Expected 'sbtRebootImpl' [error] Expected 'sbtReportResult' [error] Expected 'sbtMapExec' [error] Expected 'sbtCompleteExec' [error] sbt docs/mdoc [error] ^ sbt:chisel3>
Hi @Shorla use docs/mdoc rather.
Or you run sbt docs/mdocs directly on the terminal and not the chisel shell.
@Burnleydev1 Thank you. I was able to figure that out and it ran successfully.
I am still a bit confused though as to where the generated Verilog will appear. Is that on the terminal because it currently isn't or will I have to run something else?
cd docs/generated because when sbt docs/mdoc is run that folder is added so I think that is what is generated.
@Burnleydev1 can we do a quick zoom or google meeting for you to check out what I am doing?
@Burnleydev1 can we do a quick zoom or google meeting for you to check out what I am doing?
Sure I would love to.
@Burnleydev1 https://us04web.zoom.us/j/71405809768?pwd=R1B1UG40SUxXVWlSdlE4T2d0ZkN4Zz09 The link
Hi @Shorla , were you able to connect with @Burnleydev1 / get the docs build command to work?
I think the next step is to add the test cases:
a) what happens if you flip the direction of each of the "arrows" A, B, C (from the diagram), by swapping the left-hand-side and right-hand side? do you get an error, same verilog, or different verilog?
b) what happens if you replace the <> with a := on each of A, B, C? do you get an error, same verilog, or different verilog?
c) what happens if you add one or more val tmp = Wire(Decoupled(UInt8.W)) on each of A, B, C? For example from your Scastie, I added 2 tmp wires and got an error:
https://scastie.scala-lang.org/GEusmAM5SXSnWM5pA1bpEg
@mwachs5 when we ran docs/mdoc, a new file "generated" was formed and it got successful feedback. Does that mean I am locally set to test the code?
I am to add test cases to my scastie, My result should be directly added to the document or first be discussed here?
@mwachs5 Result from the test I carried out so far:
a) When all I did was flip the direction of each of the arrows, the Verilog remained the same, with no errors.
b) What happens if you replace the <> with a := on each of A, B, C? This error was produced for each of the arrows when <> was changed to this :=. Even when the RHS and LHS were flipped.
chisel3.internal.ChiselException: Connection between sink (DecoupledIO(IO in unelaborated Wrapper)) and source (DecoupledIO(IO io_a in PipelineStage)) failed @.bits: Sink is unwriteable by current module.
at ... ()
at Playground$Wrapper.<init>(main.scala:15)
at Playground$$anonfun$13.apply(main.scala:31)
at Playground$$anonfun$13.apply(main.scala:31)
at ... ()
at ... (Stack trace trimmed to user code only. Rerun with --full-stacktrace to see the full stack trace)
c) In a bit to connect the wires, I wanted to cut down on the errors, so I connect tmp1 and tmp2 to DontCare temporarily, I used <> and got errors, it assumed DontCare is another thing to connect. But using := solved the problem.
The best I could get it error free after the wire connection. here is my scastie link: https://scastie.scala-lang.org/yWPCBE7wQPK9iZCvqsbFrg
I am to add test cases to my scastie, My result should be directly added to the document or first be discussed here?
I think ultimately it would be nice to include the Scastie links in the document, though we haven't done that much in the documents before. But, I like the write up in your next comment, let me respond to that one.
a) When all I did was flip the direction of each of the arrows, the Verilog remained the same, with no errors.
Great, let's add that. Perhaps for each of these experiments we can add a heading with what the experiment shows. So your experiment a) shows that:
== Concept 1: <> is Communicative
// Put your code and description for for experiment a here
b) What happens if you replace the <> with a := on each of A, B, C? This error was produced for each of the arrows when <> was changed to this :=. Even when the RHS and LHS were flipped. ...
== Concept 2: := means assign ALL signals from the RHS to the LHS, regardless of their direction
??? maybe? This is frankly the thing I don't myself understand and the reason I opened this issue . I am not sure what := is supposed to mean for bi-directional signals.
In this section we can point out that following that, if you take := and try to use it to assign an input, you'll get the error that you showed.
c) In a bit to connect the wires, I wanted to cut down on the errors, so I connect tmp1 and tmp2 to DontCare temporarily, I used <> and got errors, it assumed DontCare is another thing to connect. But using := solved the problem.
Right, the := does work for DontCare for some reason I don't understand why it is different than the above case.
So maybe we need:
== Concept 3: Always Use := to assign DontCare to Wires
If you have a Wire, the direction is "unknown" so we can't use DontCare on it. But we can use := as you found: https://scastie.scala-lang.org/8Ukzm4oBTA27UtVTR72aXA
== Concept 4: You can use <> or := to assign DontCare to directioned things (IOs)
I think this is basically equivalent, because in this base both <> and := will figure out the direction from the LHS...?
== Concept 4: Use <> for intermediate wire connections
The next concept is one of the reasons I wanted to write this article.
This is an important error to show: https://scastie.scala-lang.org/AtDKcHFJSG6I4y3LstAP8A
This is showing what I expect which is that you cant <> connect two wires, because CHisel can't figure out which way things flow. It works if there is only one wire in between, because the IO and the Child IO "fix" the direction: https://scastie.scala-lang.org/sV4Z95kOReSy6Hg2w5garQ
So perhaps this should be:
== Concept 5: <> only works between things with at least one known flow (An IO or child's IO). It will fail between two wires
The best I could get it error free after the wire connection. here is my scastie link: https://scastie.scala-lang.org/yWPCBE7wQPK9iZCvqsbFrg
Your above example is compiling, but there is actually no connection A anymore (there is no connection between tmp1 and tmp2.
@mwachs5 I am excited about this because I think I might have found an answer to your concept 2 question.
== Concept 2: := means assign ALL signals from the RHS to the LHS, regardless of their direction
??? maybe? This is frankly the thing I don't myself understand and the reason I opened this issue. I am not sure what := is supposed to mean for bi-directional signals.
Before adding DecoupledIO to the arrows, := was connecting them effortlessly. But as soon as we added DecoupledIO it wasn't able to. could it be because DecoupledIO contains a bulk connection that is bi-directional? The answer is yes. So, what if I split the components of Decoupled and connect them one after the other.... I did that it worked. https://scastie.scala-lang.org/Shorla/wS03QbmgT4eNqIMdhmw4Dw/6.
Trying to connect ready in the same direction as others failed. but worked fine connecting it the other way. Here is what I think, since := can only assign signals from the RHS to the LHS and not vise-versa, it wouldn't connect bi-directional signals since there is one breaking its rule like Ready.
@mwachs5 on another note, we are due to submit our final application on Friday, November 5. Is there any particular order we are requested to fill that? How are we to go about the time line?
@mwachs5 on another note, we are due to submit our final application on Friday, November 5. Is there any particular order we are requested to fill that? How are we to go about the time line?
I think you just have to fill it out by Nov 5. I think you can log any contributions that are still in flight as "in progress" if the PR is not merged yet, if that makes sense? In other words, something that is 75% of the way there is still a valuable contribution.
@mwachs5 thank you, I got that. But there is a time line for the internship period we need to fill and that is what I am not sure how to go about. Is there a guideline to doing that?
@mwachs5 I am excited about this because I think I might have found an answer to your concept 2 question.
== Concept 2: := means assign ALL signals from the RHS to the LHS, regardless of their direction ??? maybe? This is frankly the thing I don't myself understand and the reason I opened this issue. I am not sure what := is supposed to mean for bi-directional signals.Before adding DecoupledIO to the arrows, := was connecting them effortlessly. But as soon as we added DecoupledIO it wasn't able to. could it be because DecoupledIO contains a bulk connection that is bi-directional? The answer is yes. So, what if I split the components of Decoupled and connect them one after the other.... I did that it worked. https://scastie.scala-lang.org/Shorla/wS03QbmgT4eNqIMdhmw4Dw/6.
Did you take a look at this?
But there is a time line for the internship period we need to fill and that is what I am not sure how to go about. Is there a guideline to doing that?
Hi @Shorla, my understanding is that you need to a) log all your contributions and b) fill out the final application for any project you want to apply to. For example you can go to this link https://www.outreachy.org/outreachy-december-2021-internship-round/communities/chisel/create-verilog-vs-chisel-side-by-side-comparison-o/contributions/ to submit your final application assuming that is the project you want to apply for.