Import memory files inline for Verilog generation (#1805)

This annotation adds memory import with inline generation for the
emmiter.
Supports both readmemh and readmemb statements based on argument.

1 files changed, 81 insertions, 1 deletions

diff --git a/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala b/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
index d91d97b7..93981485 100644
--- a/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
+++ b/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
@@ -40,7 +40,7 @@ case class ChiselLoadMemoryAnnotation[T <: Data](
 }
 
 
-/** [[loadMemoryFromFile]] is an annotation generator that helps with loading a memory from a text file. This relies on
+/** [[loadMemoryFromFile]] is an annotation generator that helps with loading a memory from a text file as a bind module. This relies on
   * Verilator and Verilog's `\$readmemh` or `\$readmemb`. The [[https://github.com/freechipsproject/treadle Treadle
   * backend]] can also recognize this annotation and load memory at run-time.
   *
@@ -116,6 +116,86 @@ object loadMemoryFromFile {
   }
 }
 
+
+/** [[loadMemoryFromFileInline]] is an annotation generator that helps with loading a memory from a text file inlined in
+  * the Verilog module. This relies on Verilator and Verilog's `\$readmemh` or `\$readmemb`.
+  * The [[https://github.com/freechipsproject/treadle Treadlebackend]] can also recognize this annotation and load memory at run-time.
+  *
+  * This annotation, when the FIRRTL compiler runs, triggers the [[MemoryFileInlineAnnotation]] that will add Verilog
+  * directives inlined to the module enabling the specified memories to be initialized from files.
+  * The module supports both `hex` and `bin` files by passing the appropriate [[MemoryLoadFileType.FileType]] argument with
+  * [[MemoryLoadFileType.Hex]] or [[MemoryLoadFileType.Binary]]. Hex is the default.
+  *
+  * ==Example module==
+  *
+  * Consider a simple Module containing a memory:
+  * {{{
+  * import chisel3._
+  * class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
+  *   val io = IO(new Bundle {
+  *     val address = Input(UInt(memoryType.getWidth.W))
+  *     val value   = Output(memoryType)
+  *   })
+  *   val memory = Mem(memoryDepth, memoryType)
+  *   io.value := memory(io.address)
+  * }
+  * }}}
+  *
+  * ==Above module with annotation==
+  *
+  * To load this memory from the file `/workspace/workdir/mem1.hex.txt` just add an import and annotate the memory:
+  * {{{
+  * import chisel3._
+  * import chisel3.util.experimental.loadMemoryFromFileInline   // <<-- new import here
+  * class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
+  *   val io = IO(new Bundle {
+  *     val address = Input(UInt(memoryType.getWidth.W))
+  *     val value   = Output(memoryType)
+  *   })
+  *   val memory = Mem(memoryDepth, memoryType)
+  *   io.value := memory(io.address)
+  *   loadMemoryFromFileInline(memory, "/workspace/workdir/mem1.hex.txt")  // <<-- Note the annotation here
+  * }
+  * }}}
+  *
+  * ==Example file format==
+  *
+  * A memory file should consist of ASCII text in either hex or binary format. The following example shows such a
+  * file formatted to use hex:
+  * {{{
+  *   0
+  *   7
+  *   d
+  *  15
+  * }}}
+  *
+  * A binary file can be similarly constructed.
+  * Chisel does not validate the file format or existence. It is supposed to be in a path accessible by the synthesis
+  * tool together with the generated Verilog.
+  *
+  * @see Chisel3 Wiki entry on
+  * [[https://github.com/freechipsproject/chisel3/wiki/Chisel-Memories#loading-memories-in-simulation "Loading Memories
+  * in Simulation"]]
+  */
+object loadMemoryFromFileInline {
+
+
+  /** Annotate a memory such that it can be initialized inline using a file
+    * @param memory the memory
+    * @param fileName the file used for initialization
+    * @param hexOrBinary whether the file uses a hex or binary number representation
+    */
+  def apply[T <: Data](
+    memory: MemBase[T],
+    fileName: String,
+    hexOrBinary: MemoryLoadFileType.FileType = MemoryLoadFileType.Hex
+  ): Unit = {
+    annotate(new ChiselAnnotation {
+      override def toFirrtl = MemoryFileInlineAnnotation(memory.toTarget, fileName, hexOrBinary)
+    })
+  }
+}
+
 /** This transform only is activated if Verilog is being generated (determined by presence of the proper emit
   * annotation) when activated it creates additional Verilog files that contain modules bound to the modules that
   * contain an initializable memory