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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
// See LICENSE for license details.
package chisel3.core
import chisel3.internal.Builder.pushCommand
import chisel3.internal.firrtl.Connect
import scala.language.experimental.macros
import chisel3.internal.sourceinfo._
/**
* BiConnect.connect executes a bidirectional connection element-wise.
*
* Note that the arguments are left and right (not source and sink) so the
* intent is for the operation to be commutative.
*
* The connect operation will recurse down the left Data (with the right Data).
* An exception will be thrown if a movement through the left cannot be matched
* in the right (or if the right side has extra fields).
*
* See elemConnect for details on how the root connections are issued.
*
*/
object BiConnect {
// These are all the possible exceptions that can be thrown.
case class BiConnectException(message: String) extends Exception(message)
// These are from element-level connection
def BothDriversException =
BiConnectException(": Both Left and Right are drivers")
def NeitherDriverException =
BiConnectException(": Neither Left nor Right is a driver")
def UnknownDriverException =
BiConnectException(": Locally unclear whether Left or Right (both internal)")
def UnknownRelationException =
BiConnectException(": Left or Right unavailable to current module.")
// These are when recursing down aggregate types
def MismatchedVecException =
BiConnectException(": Left and Right are different length Vecs.")
def MissingLeftFieldException(field: String) =
BiConnectException(s".$field: Left Bundle missing field ($field).")
def MissingRightFieldException(field: String) =
BiConnectException(s": Right Bundle missing field ($field).")
def MismatchedException(left: String, right: String) =
BiConnectException(s": Left ($left) and Right ($right) have different types.")
/** This function is what recursively tries to connect a left and right together
*
* There is some cleverness in the use of internal try-catch to catch exceptions
* during the recursive decent and then rethrow them with extra information added.
* This gives the user a 'path' to where in the connections things went wrong.
*/
def connect(sourceInfo: SourceInfo, connectCompileOptions: CompileOptions, left: Data, right: Data, context_mod: Module): Unit =
(left, right) match {
// Handle element case (root case)
case (left_e: Element, right_e: Element) => {
elemConnect(sourceInfo, connectCompileOptions, left_e, right_e, context_mod)
// TODO(twigg): Verify the element-level classes are connectable
}
// Handle Vec case
case (left_v: Vec[Data @unchecked], right_v: Vec[Data @unchecked]) => {
if(left_v.length != right_v.length) { throw MismatchedVecException }
for(idx <- 0 until left_v.length) {
try {
connect(sourceInfo, connectCompileOptions, left_v(idx), right_v(idx), context_mod)
} catch {
case BiConnectException(message) => throw BiConnectException(s"($idx)$message")
}
}
}
// Handle Bundle case
case (left_b: Bundle, right_b: Bundle) => {
// Verify right has no extra fields that left doesn't have
for((field, right_sub) <- right_b.elements) {
if(!left_b.elements.isDefinedAt(field)) {
if (connectCompileOptions.connectFieldsMustMatch) {
throw MissingLeftFieldException(field)
}
}
}
// For each field in left, descend with right
for((field, left_sub) <- left_b.elements) {
try {
right_b.elements.get(field) match {
case Some(right_sub) => connect(sourceInfo, connectCompileOptions, left_sub, right_sub, context_mod)
case None => {
if (connectCompileOptions.connectFieldsMustMatch) {
throw MissingRightFieldException(field)
}
}
}
} catch {
case BiConnectException(message) => throw BiConnectException(s".$field$message")
}
}
}
// Left and right are different subtypes of Data so fail
case (left, right) => throw MismatchedException(left.toString, right.toString)
}
// These functions (finally) issue the connection operation
// Issue with right as sink, left as source
private def issueConnectL2R(left: Element, right: Element)(implicit sourceInfo: SourceInfo): Unit = {
pushCommand(Connect(sourceInfo, right.lref, left.ref))
}
// Issue with left as sink, right as source
private def issueConnectR2L(left: Element, right: Element)(implicit sourceInfo: SourceInfo): Unit = {
pushCommand(Connect(sourceInfo, left.lref, right.ref))
}
// This function checks if element-level connection operation allowed.
// Then it either issues it or throws the appropriate exception.
def elemConnect(implicit sourceInfo: SourceInfo, connectCompileOptions: CompileOptions, left: Element, right: Element, context_mod: Module): Unit = {
import Direction.{Input, Output} // Using extensively so import these
// If left or right have no location, assume in context module
// This can occur if one of them is a literal, unbound will error previously
val left_mod: Module = left.binding.location.getOrElse(context_mod)
val right_mod: Module = right.binding.location.getOrElse(context_mod)
val left_direction: Option[Direction] = left.binding.direction
val right_direction: Option[Direction] = right.binding.direction
// None means internal
// CASE: Context is same module as left node and right node is in a child module
if( (left_mod == context_mod) &&
(right_mod._parent.map(_ == context_mod).getOrElse(false)) ) {
// Thus, right node better be a port node and thus have a direction hint
((left_direction, right_direction): @unchecked) match {
// CURRENT MOD CHILD MOD
case (Some(Input), Some(Input)) => issueConnectL2R(left, right)
case (None, Some(Input)) => issueConnectL2R(left, right)
case (Some(Output), Some(Output)) => issueConnectR2L(left, right)
case (None, Some(Output)) => issueConnectR2L(left, right)
case (Some(Input), Some(Output)) => throw BothDriversException
case (Some(Output), Some(Input)) => throw NeitherDriverException
case (_, None) => throw UnknownRelationException
}
}
// CASE: Context is same module as right node and left node is in child module
else if( (right_mod == context_mod) &&
(left_mod._parent.map(_ == context_mod).getOrElse(false)) ) {
// Thus, left node better be a port node and thus have a direction hint
((left_direction, right_direction): @unchecked) match {
// CHILD MOD CURRENT MOD
case (Some(Input), Some(Input)) => issueConnectR2L(left, right)
case (Some(Input), None) => issueConnectR2L(left, right)
case (Some(Output), Some(Output)) => issueConnectL2R(left, right)
case (Some(Output), None) => issueConnectL2R(left, right)
case (Some(Input), Some(Output)) => throw NeitherDriverException
case (Some(Output), Some(Input)) => throw BothDriversException
case (None, _) => throw UnknownRelationException
}
}
// CASE: Context is same module that both left node and right node are in
else if( (context_mod == left_mod) && (context_mod == right_mod) ) {
((left_direction, right_direction): @unchecked) match {
// CURRENT MOD CURRENT MOD
case (Some(Input), Some(Output)) => issueConnectL2R(left, right)
case (Some(Input), None) => issueConnectL2R(left, right)
case (None, Some(Output)) => issueConnectL2R(left, right)
case (Some(Output), Some(Input)) => issueConnectR2L(left, right)
case (Some(Output), None) => issueConnectR2L(left, right)
case (None, Some(Input)) => issueConnectR2L(left, right)
case (Some(Input), Some(Input)) => {
if (connectCompileOptions.dontAssumeDirectionality) {
throw BothDriversException
} else {
(left.binding, right.binding) match {
case (PortBinding(_, _), PortBinding(_, _)) => throw BothDriversException
case (PortBinding(_, _), _) => issueConnectL2R(left, right)
case (_, PortBinding(_, _)) => issueConnectR2L(left, right)
case _ => throw BothDriversException
}
}
}
case (Some(Output), Some(Output)) => {
if (connectCompileOptions.dontAssumeDirectionality) {
throw BothDriversException
} else {
(left.binding, right.binding) match {
case (PortBinding(_, _), PortBinding(_, _)) => throw BothDriversException
case (PortBinding(_, _), _) => issueConnectR2L(left, right)
case (_, PortBinding(_, _)) => issueConnectL2R(left, right)
case _ => throw BothDriversException
}
}
}
case (None, None) => {
if (connectCompileOptions.dontAssumeDirectionality) {
throw UnknownDriverException
} else {
issueConnectR2L(left, right)
}
}
}
}
// CASE: Context is the parent module of both the module containing left node
// and the module containing right node
// Note: This includes case when left and right in same module but in parent
else if( (left_mod._parent.map(_ == context_mod).getOrElse(false)) &&
(right_mod._parent.map(_ == context_mod).getOrElse(false))
) {
// Thus both nodes must be ports and have a direction hint
((left_direction, right_direction): @unchecked) match {
// CHILD MOD CHILD MOD
case (Some(Input), Some(Output)) => issueConnectR2L(left, right)
case (Some(Output), Some(Input)) => issueConnectL2R(left, right)
case (Some(Input), Some(Input)) => throw NeitherDriverException
case (Some(Output), Some(Output)) => throw BothDriversException
case (_, None) =>
if (connectCompileOptions.dontAssumeDirectionality) {
throw UnknownRelationException
} else {
issueConnectR2L(left, right)
}
case (None, _) =>
if (connectCompileOptions.dontAssumeDirectionality) {
throw UnknownRelationException
} else {
issueConnectR2L(left, right)
}
}
}
// Not quite sure where left and right are compared to current module
// so just error out
else throw UnknownRelationException
}
}
|
