1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
# Notes on the Compiler Plug-in
The Chisel plugin provides some operations that are too difficult, or not possbile,
to implement through regular Scala code.
# This documentation is for developers working on chisel internals.
## Compiler plugin operations
These are the two things that the compile plugin does.
1. Automatically generates the `cloneType` methods of Bundle
2. Changes the underlying mechanics of the `Bundle`s `elements` method in a way
that does not require the use of **reflection**
3. Future work: Make having a Seq[Data] in a bundle be a compiler error. See "Detecting Bundles with Seq[Data]" below.
### 1. Generating `cloneType` method
As of Mar 18, 2021, PR #1826, generating the `cloneType` method (1. above) is now the default behavior.
The cloneType method used to be a tricky thing to write for chisel developers.
For historical purposes, here is the flag was used to control that prior to full adoption.
```
-P:chiselplugin:useBundlePlugin
```
### 2. Changing `Bundle#elements` method
A `Bundle` has a default `elements` method that relies on **reflection**, which is slow and brittle, to access the list of
*fields* the bundle contains.
When enabled this second operation of the plugin examines
the `Bundle`s AST in order to determine the fields and then re-writes the underlying code of `elements`.
Technically, rewriting a lower level private method `_elementsImpl`.
It is expected that the using this feature will shortly become the default.
>The plugin should not be enabled for the `main` chisel3 project because of internal considerations.
> It is enabled for the `Test` section.
In the meantime, advanced users can try using the feature by adding the following flag to the scalac options in their
chisel projects.
```
-P:chiselplugin:buildElementAccessor
```
For example in an `build.sbt` file adding the line
```
scalacOptions += "-P:chiselplugin:genBundleElements",
```
in the appropriate place.
## Future work
### Detecting Bundles with Seq[Data]
Trying to have a `val Seq[Data]` (as opposed to a `val Vec[Data]` in a `Bundle` is a run time error.
Here is a block of code that could be added to the plugin to detect this case at compile time (with some refinement in
the detection mechanism):
```scala
if (member.isAccessor && typeIsSeqOfData(member.tpe) && !isIgnoreSeqInBundle(bundleSymbol)) {
global.reporter.error(
member.pos,
s"Bundle.field ${bundleSymbol.name}.${member.name} cannot be a Seq[Data]. " +
"Use Vec or MixedVec or mix in trait IgnoreSeqInBundle"
)
}
```
### Notes about working on the `_elementsImpl` generator for the plugin in `BundleComponent.scala`
In general the easiest way to develop and debug new code in the plugin is to use `println` statements.
Naively this can result in reams of text that can be very hard to look through.
What I found to be useful was creating some wrappers for `println` that only printed when the `Bundles` had a particular name pattern.
- Create a regular expression string in the `BundleComponent` class
- Add a printf wrapper name `show` that checks the `Bundle`'s name against the regex
- For recursive code in `getAllBundleFields` create a different wrapper `indentShow` that indents debug lines
- Sprinkle calls to these wrappers as needed for debugging
#### Bundle Regex
```scala
val bundleNameDebugRegex = "MyBundle.*"
```
#### Add `show` wrapper
`show` should be inside `case bundle` block of the `transform` method in order to have access to the current `Bundle`
```scala
def show(string: => String): Unit = {
if (bundle.symbol.name.toString.matches(bundleNameDebugRegex)) {
println(string)
}
}
```
#### Add `indentShow` wrapper
This method can be added into `BundleComponent.scala` in the `transform` method after `case Bundle`
Inside of `getAllBundleFields` I added the following code that indented for each recursion up the current
`Bundle`'s hierarchy.
```scala
def indentShow(s: => String): Unit = {
val indentString = ("-" * depth) * 2 + "> "
s.split("\n").foreach { line =>
show(indentString + line)
}
}
```
|
