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
|
// SPDX-License-Identifier: Apache-2.0
package firrtl.options
import firrtl.AnnotationSeq
import firrtl.annotations.{Annotation, NoTargetAnnotation}
import firrtl.options.Viewer.view
import java.io.File
import scopt.OptionParser
sealed trait StageOption extends Unserializable { this: Annotation => }
/** An annotation that should not be serialized automatically [[phases.WriteOutputAnnotations WriteOutputAnnotations]].
* This usually means that this is an annotation that is used only internally to a [[Stage]].
*/
trait Unserializable { this: Annotation => }
/** Mix-in that lets an [[firrtl.annotations.Annotation Annotation]] serialize itself to a file separate from the output
* annotation file.
*
* This can be used as a mechanism to serialize an [[firrtl.options.Unserializable Unserializable]] annotation or to
* write ancillary collateral used by downstream tooling, e.g., a TCL script or an FPGA constraints file. Any
* annotations using this mix-in will be serialized by the [[firrtl.options.phases.WriteOutputAnnotations
* WriteOutputAnnotations]] phase. This is one of the last phases common to all [[firrtl.options.Stage Stages]] and
* should not have to be called/included manually.
*
* Note: from the perspective of transforms generating annotations that mix-in this trait, the serialized files are not
* expected to be available to downstream transforms. Communication of information between transforms must occur
* through the annotations that will eventually be serialized to files.
*/
trait CustomFileEmission { this: Annotation =>
/** Output filename where serialized content will be written
*
* The full annotation sequence is a parameter to allow for the location where this annotation will be serialized to
* be a function of other annotations, e.g., if the location where information is written is controlled by a separate
* file location annotation.
*
* @param annotations the annotation sequence at the time of emission
*/
protected def baseFileName(annotations: AnnotationSeq): String
/** Optional suffix of the output file */
protected def suffix: Option[String]
/** A method that can convert this annotation to bytes that will be written to a file.
*
* If you only need to serialize a string, you can use the `getBytes` method:
* {{{
* def getBytes: Iterable[Byte] = myString.getBytes
* }}}
*/
def getBytes: Iterable[Byte]
/** Optionally, a sequence of annotations that will replace this annotation in the output annotation file.
*
* A non-empty implementation of this method is a mechanism for telling a downstream [[firrtl.options.Stage Stage]]
* how to deserialize the information that was serialized to a separate file. For example, if a FIRRTL circuit is
* serialized to a separate file, this method could include an input file annotation that a later stage can use to
* read the serialized FIRRTL circuit back in.
*/
def replacements(file: File): AnnotationSeq = Seq.empty
/** Method that returns the filename where this annotation will be serialized.
*
* @param annotations the annotations at the time of serialization
*/
final def filename(annotations: AnnotationSeq): File = {
val name = view[StageOptions](annotations).getBuildFileName(baseFileName(annotations), suffix)
new File(name)
}
}
/** A buffered version of [[CustomFileEmission]]
*
* This is especially useful for serializing large data structures. When emitting Strings, it makes
* it much easier to avoid materializing the entire serialized String in memory. It also helps
* avoid materializing intermediate datastructures in memory. Finally, it reduces iteration
* overhead and helps optimize I/O performance.
*
* It may seem strange to use `Array[Byte]` in an otherwise immutable API, but for maximal
* performance it is best to use the JVM primitive that file I/O uses. These Arrays should only
* used immutably even though the Java API technically does allow mutating them.
*/
trait BufferedCustomFileEmission extends CustomFileEmission { this: Annotation =>
/** A buffered version of [[getBytes]] for more efficient serialization
*
* If you only need to serialize an `Iterable[String]`, you can use the `String.getBytes` method.
* It's also helpful to create a `view` which will do the `.map` lazily instead of eagerly,
* improving GC performance.
* {{{
* def getBytesBuffered: Iterable[Array[Byte]] = myListString.view.map(_.getBytes)
* }}}
*/
def getBytesBuffered: Iterable[Array[Byte]]
final def getBytes: Iterable[Byte] = getBytesBuffered.flatten
}
/** Holds the name of the target directory
* - set with `-td/--target-dir`
* - if unset, a [[TargetDirAnnotation]] will be generated with the
* @param value target directory name
*/
case class TargetDirAnnotation(directory: String = ".") extends NoTargetAnnotation with StageOption
object TargetDirAnnotation extends HasShellOptions {
val options = Seq(
new ShellOption[String](
longOption = "target-dir",
toAnnotationSeq = (a: String) => Seq(TargetDirAnnotation(a)),
helpText = "Work directory (default: '.')",
shortOption = Some("td"),
helpValueName = Some("<directory>")
)
)
}
/** Additional arguments
* - set with any trailing option on the command line
* @param value one [[scala.Predef.String String]] argument
*/
case class ProgramArgsAnnotation(arg: String) extends NoTargetAnnotation with StageOption
object ProgramArgsAnnotation {
def addOptions(p: OptionParser[AnnotationSeq]): Unit = p
.arg[String]("<arg>...")
.unbounded()
.optional()
.action((x, c) => ProgramArgsAnnotation(x) +: c)
.text("optional unbounded args")
}
/** Holds a filename containing one or more [[annotations.Annotation]] to be read
* - set with `-faf/--annotation-file`
* @param value input annotation filename
*/
case class InputAnnotationFileAnnotation(file: String) extends NoTargetAnnotation with StageOption
object InputAnnotationFileAnnotation extends HasShellOptions {
val options = Seq(
new ShellOption[String](
longOption = "annotation-file",
toAnnotationSeq = (a: String) => Seq(InputAnnotationFileAnnotation(a)),
helpText = "An input annotation file",
shortOption = Some("faf"),
helpValueName = Some("<file>")
)
)
}
/** An explicit output _annotation_ file to write to
* - set with `-foaf/--output-annotation-file`
* @param value output annotation filename
*/
case class OutputAnnotationFileAnnotation(file: String) extends NoTargetAnnotation with StageOption
object OutputAnnotationFileAnnotation extends HasShellOptions {
val options = Seq(
new ShellOption[String](
longOption = "output-annotation-file",
toAnnotationSeq = (a: String) => Seq(OutputAnnotationFileAnnotation(a)),
helpText = "An output annotation file",
shortOption = Some("foaf"),
helpValueName = Some("<file>")
)
)
}
/** If this [[firrtl.annotations.Annotation Annotation]] exists in an [[firrtl.AnnotationSeq AnnotationSeq]], then a
* [[firrtl.options.phases.WriteOutputAnnotations WriteOutputAnnotations]] will include
* [[firrtl.annotations.DeletedAnnotation DeletedAnnotation]]s when it writes to a file.
* - set with '--write-deleted'
*/
case object WriteDeletedAnnotation extends NoTargetAnnotation with StageOption with HasShellOptions {
val options = Seq(
new ShellOption[Unit](
longOption = "write-deleted",
toAnnotationSeq = (_: Unit) => Seq(WriteDeletedAnnotation),
helpText = "Include deleted annotations in the output annotation file"
)
)
}
|
