Add feature to allow external I/O signals

Johan Peltenburg · Johan Peltenburg · commit 6d5ecde47c96 · 2020-11-11T10:59:47.000+01:00
diff --git a/codegen/cpp/fletchgen/CMakeLists.txt b/codegen/cpp/fletchgen/CMakeLists.txt
@@ -65,6 +65,7 @@ add_compile_unit(
     src/fletchgen/nucleus.cc
     src/fletchgen/profiler.cc
     src/fletchgen/axi4_lite.cc
+    src/fletchgen/external.cc
 
     src/fletchgen/srec/recordbatch.cc
     src/fletchgen/srec/srec.cc
diff --git a/codegen/cpp/fletchgen/README.md b/codegen/cpp/fletchgen/README.md
@@ -94,6 +94,56 @@ your kernel implementation.
 | fletcher_profile   | true / false    | false   | If set to true, mark this field for profiling. The hardware streams resulting from this field will have a profiler attached to them.  |
 | fletcher_tag_width | 1 / 2 / 3 / ... | 1       | Width of the `tag` field of commands and unlock streams of RecordBatchReaders/Writers. Can be used to identify commands.              |
 
+# Custom MMIO registers
+You can add custom MMIO registers to your kernel using `--reg`.
+More information [can be found here](../../../docs/mmio.md).
+
+# Custom external I/O
+
+Sometimes, your kernel requires other I/O signals than just Arrow data streams
+in and out, and MMIO registers. There may be some other type of data source or
+sink in your design, there may be some platform-specific things you want to use,
+or etcetera.
+
+You can supply Fletchgen with a YAML file describing what signals you want to
+draw between the kernel and the top-level. An example is shown below, where we
+want to handshake completion from the platform top-level with a `req` and `ack`
+bit.
+
+```yaml
+- record:
+  name: platform
+  fields:
+  - record:
+    name: complete
+    fields:
+    - field:
+      name: req
+      width: 1
+    - field:
+      name: ack
+      width: 1
+      reverse: true
+```
+
+This will result in the following signals appearing at the top-level:
+```vhdl
+ext_platform_complete_req : out std_logic;
+ext_platform_complete_ack : in  std_logic
+```
+
+* The signals are assumed to be driven by the kernel. To drive them from the top
+  level, use:
+```yaml
+reverse: true
+```
+
+* Fields with a width of 1 can be forced to be `std_logic_vector` instead of 
+  `std_logic` by using:
+```yaml
+vector: true
+```
+
 # Further reading
 
 You can generate a simulation top level and provide a Flatbuffer file with a
diff --git a/codegen/cpp/fletchgen/src/fletchgen/design.cc b/codegen/cpp/fletchgen/src/fletchgen/design.cc
@@ -14,6 +14,7 @@
 
 #include <cerata/api.h>
 #include <cerata/vhdl/vhdl.h>
+#include <cerata/yaml/yaml.h>
 
 #include <string>
 #include <vector>
@@ -27,6 +28,7 @@
 #include "fletchgen/mmio.h"
 #include "fletchgen/profiler.h"
 #include "fletchgen/bus.h"
+#include "fletchgen/external.h"
 
 namespace fletchgen {
 
@@ -160,6 +162,7 @@ Design::Design(const std::shared_ptr<Options> &opts) {
   // Analyze schemas and recordbatches to get schema_set and batch_desc
   AnalyzeSchemas();
   AnalyzeRecordBatches();
+  AnalyzeExternalIO();
   // Sanity check our design for equal number of schemas and recordbatch descriptions.
   if (schema_set->schemas().size() != batch_desc.size()) {
     FLETCHER_LOG(FATAL, "Number of Schemas and RecordBatchDescriptions does not match.");
@@ -250,4 +253,27 @@ std::vector<cerata::OutputSpec> Design::GetOutputSpec() {
   return result;
 }
 
+void Design::AnalyzeExternalIO() {
+  if (!options->externals_yaml.empty()) {
+    // Read YAML
+    auto fs = std::ifstream(options->externals_yaml);
+    std::stringstream yaml;
+    yaml << fs.rdbuf();
+
+    // Convert to field
+    std::shared_ptr<cerata::Field> field;
+    auto converter = cerata::yaml::YamlConverter(yaml.str(), &field);
+    auto status = converter.Convert();
+    if (!status.ok()) {
+      FLETCHER_LOG(FATAL, status.msg());
+    }
+
+    // Extract and store type
+    auto ext_type = field->type();
+    ext_type->SetName("_external");
+    cerata::default_type_pool()->Add(ext_type);
+    external = ext_type;
+  }
+}
+
 }  // namespace fletchgen
diff --git a/codegen/cpp/fletchgen/src/fletchgen/design.h b/codegen/cpp/fletchgen/src/fletchgen/design.h
@@ -41,6 +41,8 @@ struct Design {
   void AnalyzeSchemas();
   /// @brief Analyze the supplied RecordBatches.
   void AnalyzeRecordBatches();
+  /// @brief Analyze custom IO.
+  void AnalyzeExternalIO();
 
   /// The program options.
   std::shared_ptr<Options> options;
@@ -61,6 +63,9 @@ struct Design {
 
   Axi4LiteSpec mmio_spec;
 
+  /// External signals type
+  std::optional<std::shared_ptr<Type>> external;
+
   /// The RecordBatchDescriptions to use in SREC generation.
   std::vector<fletcher::RecordBatchDescription> batch_desc;
 
diff --git a/codegen/cpp/fletchgen/src/fletchgen/external.cc b/codegen/cpp/fletchgen/src/fletchgen/external.cc
@@ -0,0 +1,32 @@
+// Copyright 2018-2020 Delft University of Technology
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <map>
+#include <cerata/api.h>
+
+#include "fletchgen/external.h"
+#include "fletchgen/status.h"
+
+namespace fletchgen {
+
+auto external() -> std::optional<std::shared_ptr<cerata::Type>> {
+  auto opt = cerata::default_type_pool()->Get("_external");
+  if (opt) {
+    return opt.value()->shared_from_this();
+  } else {
+    return std::nullopt;
+  }
+}
+
+}
diff --git a/codegen/cpp/fletchgen/src/fletchgen/external.h b/codegen/cpp/fletchgen/src/fletchgen/external.h
@@ -0,0 +1,23 @@
+// Copyright 2018-2020 Delft University of Technology
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <cerata/api.h>
+
+#include "fletchgen/status.h"
+
+namespace fletchgen {
+
+auto external() -> std::optional<std::shared_ptr<cerata::Type>>;
+
+}
diff --git a/codegen/cpp/fletchgen/src/fletchgen/fletchgen.cc b/codegen/cpp/fletchgen/src/fletchgen/fletchgen.cc
@@ -141,7 +141,11 @@ int fletchgen(int argc, char **argv) {
     std::string axi_file_path = options->output_dir + "/vhdl/AxiTop.gen.vhd";
     FLETCHER_LOG(INFO, "Saving AXI top-level design to: " + axi_file_path);
     axi_file = std::ofstream(axi_file_path);
-    fletchgen::top::GenerateAXITop(*design.mantle_comp, *design.schema_set, {&axi_file}, design.mmio_spec);
+    fletchgen::top::GenerateAXITop(*design.mantle_comp,
+                                   *design.schema_set,
+                                   design.mmio_spec,
+                                   design.external,
+                                   {&axi_file});
     axi_file.close();
   }
 
diff --git a/codegen/cpp/fletchgen/src/fletchgen/kernel.cc b/codegen/cpp/fletchgen/src/fletchgen/kernel.cc
@@ -22,6 +22,7 @@
 #include "fletchgen/basic_types.h"
 #include "fletchgen/mmio.h"
 #include "fletchgen/array.h"
+#include "fletchgen/external.h"
 
 namespace fletchgen {
 
@@ -46,6 +47,7 @@ Kernel::Kernel(std::string name,
 
   auto iw = index_width();
   auto tw = tag_width();
+
   Add({iw, tw});
 
   // Add ports going to/from RecordBatches.
@@ -81,6 +83,11 @@ Kernel::Kernel(std::string name,
     }
   }
 
+  // Add custom I/O
+  auto ext = external();
+  if (ext) {
+    Add(cerata::port("ext", ext.value(), Port::Dir::OUT));
+  }
 }
 
 std::shared_ptr<Kernel> kernel(const std::string &name,
diff --git a/codegen/cpp/fletchgen/src/fletchgen/mantle.cc b/codegen/cpp/fletchgen/src/fletchgen/mantle.cc
@@ -27,6 +27,7 @@
 #include "fletchgen/bus.h"
 #include "fletchgen/nucleus.h"
 #include "fletchgen/axi4_lite.h"
+#include "fletchgen/external.h"
 
 namespace fletchgen {
 
@@ -174,6 +175,14 @@ Mantle::Mantle(std::string name,
     // Append the PortArray and connect.
     Connect(array->Append(), bp);
   }
+
+  // Add and connect platform IO
+  auto ext = external();
+  if (ext) {
+    auto pf = cerata::port("ext", ext.value(), Port::Dir::OUT);
+    Add(pf);
+    Connect(pf, nucleus_inst_->prt("ext"));
+  }
 }
 
 /// @brief Construct a Mantle and return a shared pointer to it.
diff --git a/codegen/cpp/fletchgen/src/fletchgen/nucleus.cc b/codegen/cpp/fletchgen/src/fletchgen/nucleus.cc
@@ -25,6 +25,7 @@
 #include "fletchgen/mmio.h"
 #include "fletchgen/profiler.h"
 #include "fletchgen/axi4_lite.h"
+#include "fletchgen/external.h"
 
 namespace fletchgen {
 
@@ -208,6 +209,14 @@ Nucleus::Nucleus(const std::string &name,
 
   // Gather all Field-derived ports that require profiling on this Nucleus.
   ProfileDataStreams(mmio_inst);
+
+  // Add and connect platform IO
+  auto ext = external();
+  if (ext) {
+    auto pf = cerata::port("ext", ext.value(), Port::Dir::OUT);
+    Add(pf);
+    Connect(pf, kernel_inst->prt("ext"));
+  }
 }
 
 std::shared_ptr<Nucleus> nucleus(const std::string &name,
diff --git a/codegen/cpp/fletchgen/src/fletchgen/options.cc b/codegen/cpp/fletchgen/src/fletchgen/options.cc
@@ -68,6 +68,9 @@ bool Options::Parse(Options *options, int argc, char **argv) {
                  "step of the simulation. Init must be a hexadecimal value in the form of 0x01234ABCD.\n"
                  "Example: \"-reg32 c:32:myh2kreg:0xDEADBEEF s:64:mk2hreg\"");
 
+  app.add_option("-e,--external", options->externals_yaml, "Path to YAML file describing external signals to drag "
+                                                           "between kernel and top-level.");
+
   app.add_option("--bus_specs", options->bus_dims,
                  "Specify top-level bus parameters.\n"
                  "Value must be a tuple of the following form: \"aw,dw,lw,bs,bm\"\n"
diff --git a/codegen/cpp/fletchgen/src/fletchgen/options.h b/codegen/cpp/fletchgen/src/fletchgen/options.h
@@ -44,6 +44,8 @@ struct Options {
   std::string kernel_name = "Kernel";
   /// Custom 32-bit registers.
   std::vector<std::string> regs;
+  /// File to parse for external signals to/from top level to kernel.
+  std::string externals_yaml;
   /// Bus dimensions strings.
   std::vector<std::string> bus_dims = {"64,512,8,1,16"};
   /// Use 64-bits data width for AXI4-lite MMIO bus when true.
diff --git a/codegen/cpp/fletchgen/src/fletchgen/status.h b/codegen/cpp/fletchgen/src/fletchgen/status.h
@@ -0,0 +1,38 @@
+// Copyright 2018-2020 Delft University of Technology
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <iostream>
+
+#include <putong/status.h>
+
+namespace fletchgen {
+
+/// Return on error status.
+#define FLETCHGEN_ROE(s) {         \
+  auto status = s;                 \
+  if (!status.ok()) return status; \
+}                                  \
+void()
+
+/// Error types.
+enum class Error {
+  GenericError,
+  YAMLError
+};
+
+using Status = putong::Status<Error>;
+
+}
diff --git a/codegen/cpp/fletchgen/src/fletchgen/top/axi.cc b/codegen/cpp/fletchgen/src/fletchgen/top/axi.cc
@@ -18,6 +18,9 @@
 #include <cerata/vhdl/vhdl.h>
 #include <memory>
 
+#include <cerata/api.h>
+#include <cerata/vhdl/vhdl.h>
+
 #include "fletchgen/top/axi_template.h"
 #include "fletchgen/mantle.h"
 
@@ -27,8 +30,9 @@ using cerata::vhdl::Template;
 
 std::string GenerateAXITop(const Mantle &mantle,
                            const SchemaSet &schema_set,
-                           const std::vector<std::ostream *> &outputs,
-                           Axi4LiteSpec axi_spec) {
+                           Axi4LiteSpec axi_spec,
+                           std::optional<std::shared_ptr<Type>> external,
+                           const std::vector<std::ostream *> &outputs) {
   // Template for AXI top level
   auto t = Template::FromString(axi_source);
 
@@ -186,6 +190,25 @@ std::string GenerateAXITop(const Mantle &mantle,
     t.Replace("AXI_WRITE_CONVERTER", "");
   }
 
+  t.Replace("MANTLE_DECL", cerata::vhdl::Decl::Generate(mantle, false, 1).ToString());
+
+  if (external) {
+    auto p_mantle = cerata::port("ext", external.value(), cerata::Port::Dir::OUT);
+    auto p_top = cerata::port("ext", external.value(), cerata::Port::Dir::OUT);
+    cerata::Connect(p_top, p_mantle);
+
+    auto decl_block = cerata::vhdl::Decl::Generate(*p_mantle, 2);
+    decl_block <<= ";";
+    auto inst_block = cerata::vhdl::Inst::GeneratePortMaps(*p_mantle);
+    inst_block.indent = 3;
+    inst_block << ",";
+
+    t.Replace("EXTERNAL_PORT_DECL", decl_block.ToString());
+    t.Replace("EXTERNAL_INST_MAP", inst_block.ToString());
+  } else {
+    t.Replace("EXTERNAL_PORT_DECL", "");
+  }
+
   for (auto &o : outputs) {
     o->flush();
     *o << t.ToString();
diff --git a/codegen/cpp/fletchgen/src/fletchgen/top/axi.h b/codegen/cpp/fletchgen/src/fletchgen/top/axi.h
diff --git a/codegen/cpp/fletchgen/src/fletchgen/top/axi_template.h b/codegen/cpp/fletchgen/src/fletchgen/top/axi_template.h
diff --git a/codegen/cpp/fletchgen/src/fletchgen/top/sim.cc b/codegen/cpp/fletchgen/src/fletchgen/top/sim.cc
diff --git a/codegen/cpp/fletchgen/src/fletchgen/top/sim_template.h b/codegen/cpp/fletchgen/src/fletchgen/top/sim_template.h
