Merge pull request #311 from lnis-uofu/report_bitstream

Report bitstream distribution

docs/source/manual/file_formats/bitstream_distribution_file.rst

@@ -0,0 +1,50 @@
+.. _file_format_bitstream_distribution_file:
+
+Bitstream Distribution File (.xml)
+----------------------------------
+
+The bitstream distribution file aims to show 
+
+- The total number of configuration bits under each block
+- The number of configuration bits per block 
+
+An example of design constraints is shown as follows.
+
+.. code-block:: xml
+
+  <block name="fpga_top" number_of_bits="527">
+  	<block name="grid_clb_1__1_" number_of_bits="136">
+  	</block>
+  	<block name="grid_io_top_1__2_" number_of_bits="8">
+  	</block>
+  	<block name="grid_io_right_2__1_" number_of_bits="8">
+  	</block>
+  	<block name="grid_io_bottom_1__0_" number_of_bits="8">
+  	</block>
+  	<block name="grid_io_left_0__1_" number_of_bits="8">
+  	</block>
+  	<block name="sb_0__0_" number_of_bits="58">
+  	</block>
+  	<block name="sb_0__1_" number_of_bits="57">
+  	</block>
+  	<block name="sb_1__0_" number_of_bits="59">
+  	</block>
+  	<block name="sb_1__1_" number_of_bits="56">
+  	</block>
+  	<block name="cbx_1__0_" number_of_bits="33">
+  	</block>
+  	<block name="cbx_1__1_" number_of_bits="33">
+  	</block>
+  	<block name="cby_0__1_" number_of_bits="30">
+  	</block>
+  	<block name="cby_1__1_" number_of_bits="33">
+  	</block>
+  </block>
+
+.. option:: name="<string>"
+
+  The block name represents the instance name which you can find in the fabric netlists
+
+.. option:: number_of_bits="<string>"
+
+  The total number of configuration bits in this block

docs/source/manual/file_formats/index.rst

@@ -23,3 +23,5 @@ OpenFPGA widely uses XML format for interchangable files
    fabric_key
 
    io_mapping_file
+
+   bitstream_distribution_file

docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst

@@ -87,4 +87,22 @@ write_io_mapping
 
     Show verbose log
 
+report_bitstream_distribution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Output the bitstream distribution to a file
+
+  .. option:: --file <string> or -f <string>
+
+    Specify the file name where the bitstream distribution will be outputted to.
+    See file formats in :ref:`file_format_bitstream_distribution_file`.
+
+  .. option:: --depth <int> or -d <int>
+
+    Specify the maximum depth of the block which should appear in the block
+
+  .. option:: --verbose
+
+    Show verbose log
+
 

libopenfpga/libfpgabitstream/src/bitstream_manager_utils.cpp

@@ -71,5 +71,27 @@ size_t find_bitstream_manager_config_bit_index_in_parent_block(const BitstreamMa
   return curr_index;
 }
 
+/********************************************************************
+ * Find the total number of configuration bits under a block
+ * As configuration bits are stored only under the leaf blocks,
+ * this function will recursively visit all the child blocks
+ * until reaching a leaf block, where we collect the number of bits
+ *******************************************************************/
+size_t rec_find_bitstream_manager_block_sum_of_bits(const BitstreamManager& bitstream_manager,
+                                                    const ConfigBlockId& block) {
+  /* For leaf block, return directly with the number of bits, because it has not child block */
+  if (0 < bitstream_manager.block_bits(block).size()) {
+    VTR_ASSERT_SAFE(bitstream_manager.block_children(block).empty());
+    return bitstream_manager.block_bits(block).size();
+  }
+
+  size_t sum_of_bits = 0;
+  /* Dive to child blocks if this block has any */
+  for (const ConfigBlockId& child_block : bitstream_manager.block_children(block)) {
+    sum_of_bits += rec_find_bitstream_manager_block_sum_of_bits(bitstream_manager, child_block);
+  }
+
+  return sum_of_bits;
+}
 
 } /* end namespace openfpga */

libopenfpga/libfpgabitstream/src/bitstream_manager_utils.h

@@ -22,6 +22,9 @@ std::vector<ConfigBlockId> find_bitstream_manager_top_blocks(const BitstreamMana
 size_t find_bitstream_manager_config_bit_index_in_parent_block(const BitstreamManager& bitstream_manager,
                                                                const ConfigBitId& bit_id);
 
+size_t rec_find_bitstream_manager_block_sum_of_bits(const BitstreamManager& bitstream_manager,
+                                                    const ConfigBlockId& block);
+
 } /* end namespace openfpga */
 
 #endif

libopenfpga/libfpgabitstream/src/report_arch_bitstream_distribution.cpp

@@ -0,0 +1,124 @@
+/********************************************************************
+ * This file includes functions that report distribution of bitstream by blocks
+ *******************************************************************/
+#include <chrono>
+#include <ctime>
+#include <fstream>
+
+/* Headers from vtrutil library */
+#include "vtr_assert.h"
+#include "vtr_log.h"
+#include "vtr_time.h"
+
+/* Headers from openfpgautil library */
+#include "openfpga_digest.h"
+#include "openfpga_tokenizer.h"
+#include "openfpga_version.h"
+
+#include "openfpga_reserved_words.h"
+
+#include "bitstream_manager_utils.h"
+#include "report_arch_bitstream_distribution.h"
+
+/* begin namespace openfpga */
+namespace openfpga {
+
+/********************************************************************
+ * This function write header information for an XML file of bitstream distribution
+ *******************************************************************/
+static 
+void report_architecture_bitstream_distribution_xml_file_head(std::fstream& fp) {
+  valid_file_stream(fp);
+ 
+  auto end = std::chrono::system_clock::now(); 
+  std::time_t end_time = std::chrono::system_clock::to_time_t(end);
+
+  fp << "<!-- " << std::endl;
+  fp << "\t- Report Architecture Bitstream Distribution" << std::endl;
+  fp << "\t- Version: " << openfpga::VERSION << std::endl;
+  fp << "\t- Date: " << std::ctime(&end_time) ;
+  fp << "--> " << std::endl;
+  fp << std::endl;
+}
+
+/********************************************************************
+ * Recursively report the bitstream distribution of a block to a file
+ * This function will use a Depth-First Search in outputting bitstream
+ * for each block 
+ * For block with child blocks, we visit each child recursively
+ * The reporting can be stopped at a given maximum hierarchy level 
+ * which is used to limit the length of the report
+ *******************************************************************/
+static 
+void rec_report_block_bitstream_distribution_to_xml_file(std::fstream& fp,
+                                                         const BitstreamManager& bitstream_manager, 
+                                                         const ConfigBlockId& block,
+                                                         const size_t& max_hierarchy_level,
+                                                         const size_t& hierarchy_level) {
+  valid_file_stream(fp);
+
+  if (hierarchy_level > max_hierarchy_level) {
+    return;
+  }
+
+  /* Write the bitstream distribution of this block */
+  write_tab_to_file(fp, hierarchy_level);
+  fp << "<block";
+  fp << " name=\"" << bitstream_manager.block_name(block)<< "\"";
+  fp << " number_of_bits=\"" << rec_find_bitstream_manager_block_sum_of_bits(bitstream_manager, block) << "\"";
+  fp << ">" << std::endl;
+
+  /* Dive to child blocks if this block has any */
+  for (const ConfigBlockId& child_block : bitstream_manager.block_children(block)) {
+    rec_report_block_bitstream_distribution_to_xml_file(fp, bitstream_manager, child_block,
+                                                        max_hierarchy_level, hierarchy_level + 1);
+  }
+
+  write_tab_to_file(fp, hierarchy_level);
+  fp << "</block>" <<std::endl;
+}
+
+/********************************************************************
+ * Report the distribution of bitstream by blocks, e.g., the number of
+ * configuration bits per SB/CB/CLB
+ * This function can generate a report to a file 
+ *
+ * Notes: 
+ *   - The output format is a table whose format is compatible with RST files
+ *******************************************************************/
+int report_architecture_bitstream_distribution(const BitstreamManager& bitstream_manager,
+                                               const std::string& fname,
+                                               const size_t& max_hierarchy_level) {
+  /* Ensure that we have a valid file name */
+  if (true == fname.empty()) {
+    VTR_LOG_ERROR("Received empty file name to report bitstream!\n\tPlease specify a valid file name.\n");
+    return 1;
+  }
+
+  std::string timer_message = std::string("Report architecture bitstream distribution into XML file '") + fname + std::string("'");
+  vtr::ScopedStartFinishTimer timer(timer_message);
+
+  /* Create the file stream */
+  std::fstream fp;
+  fp.open(fname, std::fstream::out | std::fstream::trunc);
+
+  check_file_stream(fname.c_str(), fp);
+
+  /* Put down a brief introduction */
+  report_architecture_bitstream_distribution_xml_file_head(fp);
+
+  /* Find the top block, which has not parents */
+  std::vector<ConfigBlockId> top_block = find_bitstream_manager_top_blocks(bitstream_manager);
+  /* Make sure we have only 1 top block */
+  VTR_ASSERT(1 == top_block.size());
+
+  /* Write bitstream, block by block, in a recursive way */
+  rec_report_block_bitstream_distribution_to_xml_file(fp, bitstream_manager, top_block[0], max_hierarchy_level, 0);
+
+  /* Close file handler */
+  fp.close();
+
+  return 0;
+}
+
+} /* end namespace openfpga */

libopenfpga/libfpgabitstream/src/report_arch_bitstream_distribution.h

@@ -0,0 +1,23 @@
+#ifndef REPORT_ARCH_BITSTREAM_DISTRIBUTION_H
+#define REPORT_ARCH_BITSTREAM_DISTRIBUTION_H
+
+/********************************************************************
+ * Include header files that are required by function declaration
+ *******************************************************************/
+#include <string>
+#include "bitstream_manager.h"
+
+/********************************************************************
+ * Function declaration
+ *******************************************************************/
+
+/* begin namespace openfpga */
+namespace openfpga {
+
+int report_architecture_bitstream_distribution(const BitstreamManager& bitstream_manager,
+                                               const std::string& fname,
+                                               const size_t& max_hierarchy_level = 1);
+
+} /* end namespace openfpga */
+
+#endif

libopenfpga/libfpgabitstream/test/test_arch_bitstream.cpp

@@ -10,17 +10,18 @@
 /* Headers from fabric key */
 #include "read_xml_arch_bitstream.h"
 #include "write_xml_arch_bitstream.h"
+#include "report_arch_bitstream_distribution.h"
 
 int main(int argc, const char** argv) {
-  /* Ensure we have only one or two argument */
-  VTR_ASSERT((2 == argc) || (3 == argc));
+  /* Ensure we have only one or two or 3 argument */
+  VTR_ASSERT((2 == argc) || (3 == argc) || (4 == argc));
 
   /* Parse the bitstream from an XML file */
   openfpga::BitstreamManager test_bitstream = openfpga::read_xml_architecture_bitstream(argv[1]);
   VTR_LOG("Read the bitstream from an XML file: %s.\n",
           argv[1]);
 
-  /* Output the circuit library to an XML file
+  /* Output the bitstream database to an XML file
    * This is optional only used when there is a second argument
    */
   if (3 <= argc) { 
@@ -28,6 +29,15 @@ int main(int argc, const char** argv) {
     VTR_LOG("Echo the bitstream to an XML file: %s.\n",
             argv[2]);
   }
+  /* Output the bitstream distribution to an XML file
+   * This is optional only used when there is a third argument
+   */
+  if (4 <= argc) { 
+    openfpga::report_architecture_bitstream_distribution(test_bitstream, argv[3]);
+    VTR_LOG("Echo the bitstream distribution to an XML file: %s.\n",
+            argv[3]);
+  }
+
 }
 
 

openfpga/src/base/openfpga_bitstream.cpp

@@ -14,6 +14,7 @@
 /* Headers from fpgabitstream library */
 #include "read_xml_arch_bitstream.h"
 #include "write_xml_arch_bitstream.h"
+#include "report_arch_bitstream_distribution.h"
 
 #include "openfpga_naming.h"
 
@@ -165,4 +166,41 @@ int write_io_mapping(const OpenfpgaContext& openfpga_ctx,
   return status;
 } 
 
+/********************************************************************
+ * A wrapper function to call the report_arch_bitstream_distribution() in FPGA bitstream
+ *******************************************************************/
+int report_bitstream_distribution(const OpenfpgaContext& openfpga_ctx,
+                                  const Command& cmd, const CommandContext& cmd_context) {
+
+  CommandOptionId opt_file = cmd.option("file");
+
+  int status = CMD_EXEC_SUCCESS;
+  
+  VTR_ASSERT(true == cmd_context.option_enable(cmd, opt_file));
+
+  std::string src_dir_path = find_path_dir_name(cmd_context.option_value(cmd, opt_file));
+
+  /* Create directories */
+  create_directory(src_dir_path);
+
+  /* Default depth requirement, this is to limit the report size by default */
+  int depth = 1;
+  CommandOptionId opt_depth = cmd.option("depth");
+  if (true == cmd_context.option_enable(cmd, opt_depth)) {
+    depth = std::atoi(cmd_context.option_value(cmd, opt_depth).c_str());
+    /* Error out if we have negative depth */
+    if (0 > depth) {
+      VTR_LOG_ERROR("Invalid depth '%d' which should be 0 or a positive number!\n",
+                    depth);
+      return CMD_EXEC_FATAL_ERROR; 
+    }
+  }
+
+  status = report_architecture_bitstream_distribution(openfpga_ctx.bitstream_manager(),
+                                                      cmd_context.option_value(cmd, opt_file),
+                                                      depth);
+  
+  return status;
+}
+
 } /* end namespace openfpga */

openfpga/src/base/openfpga_bitstream.h

@@ -27,6 +27,9 @@ int write_fabric_bitstream(const OpenfpgaContext& openfpga_ctx,
 int write_io_mapping(const OpenfpgaContext& openfpga_ctx,
                      const Command& cmd, const CommandContext& cmd_context);
 
+int report_bitstream_distribution(const OpenfpgaContext& openfpga_ctx,
+                                  const Command& cmd, const CommandContext& cmd_context);
+
 } /* end namespace openfpga */
 
 #endif

openfpga/src/base/openfpga_bitstream_command.cpp

@@ -72,6 +72,40 @@ ShellCommandId add_openfpga_build_arch_bitstream_command(openfpga::Shell<Openfpg
   return shell_cmd_id;
 }
 
+/********************************************************************
+ * - Add a command to Shell environment: report_bitstream_distribution
+ * - Add associated options 
+ * - Add command dependency
+ *******************************************************************/
+static 
+ShellCommandId add_openfpga_report_bitstream_distribution_command(openfpga::Shell<OpenfpgaContext>& shell,
+                                                                  const ShellCommandClassId& cmd_class_id,
+                                                                  const std::vector<ShellCommandId>& dependent_cmds) {
+  Command shell_cmd("report_bitstream_distribution");
+
+  /* Add an option '--file' */
+  CommandOptionId opt_file = shell_cmd.add_option("file", true, "file path to output the bitstream distribution");
+  shell_cmd.set_option_short_name(opt_file, "f");
+  shell_cmd.set_option_require_value(opt_file, openfpga::OPT_STRING);
+
+  /* Add an option '--depth' */
+  CommandOptionId opt_depth = shell_cmd.add_option("depth", false, "Specify the max. depth of blocks which will appear in report");
+  shell_cmd.set_option_require_value(opt_depth, openfpga::OPT_STRING);
+
+  /* Add an option '--verbose' */
+  shell_cmd.add_option("verbose", false, "Enable verbose output");
+  
+  /* Add command 'report_bitstream_distribution' to the Shell */
+  ShellCommandId shell_cmd_id = shell.add_command(shell_cmd, "Report bitstream distribution");
+  shell.set_command_class(shell_cmd_id, cmd_class_id);
+  shell.set_command_execute_function(shell_cmd_id, report_bitstream_distribution);
+
+  /* Add command dependency to the Shell */
+  shell.set_command_dependency(shell_cmd_id, dependent_cmds);
+
+  return shell_cmd_id;
+}
+
 /********************************************************************
  * - Add a command to Shell environment: build_fabric_bitstream
  * - Add associated options 
@@ -187,6 +221,14 @@ void add_openfpga_bitstream_commands(openfpga::Shell<OpenfpgaContext>& shell) {
   cmd_dependency_build_arch_bitstream.push_back(shell_cmd_repack_id);
   ShellCommandId shell_cmd_build_arch_bitstream_id = add_openfpga_build_arch_bitstream_command(shell, openfpga_bitstream_cmd_class, cmd_dependency_build_arch_bitstream);
 
+  /******************************** 
+   * Command 'report_bitstream_distribution' 
+   */
+  /* The 'report_bitstream_distribution' command should NOT be executed before 'build_architecture_bitstream' */
+  std::vector<ShellCommandId> cmd_dependency_report_bitstream_distribution;
+  cmd_dependency_build_arch_bitstream.push_back(shell_cmd_build_arch_bitstream_id);
+  add_openfpga_report_bitstream_distribution_command(shell, openfpga_bitstream_cmd_class, cmd_dependency_report_bitstream_distribution);
+
   /******************************** 
    * Command 'build_fabric_bitstream' 
    */

openfpga_flow/openfpga_shell_scripts/report_bitstream_distribution_example_script.openfpga

@@ -0,0 +1,54 @@
+# Run VPR for the 'and' design
+#--write_rr_graph example_rr_graph.xml
+vpr ${VPR_ARCH_FILE} ${VPR_TESTBENCH_BLIF} --clock_modeling route --absorb_buffer_luts off
+
+# Read OpenFPGA architecture definition
+read_openfpga_arch -f ${OPENFPGA_ARCH_FILE}
+
+# Read OpenFPGA simulation settings
+read_openfpga_simulation_setting -f ${OPENFPGA_SIM_SETTING_FILE}
+
+# Annotate the OpenFPGA architecture to VPR data base
+# to debug use --verbose options
+link_openfpga_arch --activity_file ${ACTIVITY_FILE} --sort_gsb_chan_node_in_edges
+
+# Check and correct any naming conflicts in the BLIF netlist
+check_netlist_naming_conflict --fix --report ./netlist_renaming.xml
+
+# Apply fix-up to clustering nets based on routing results
+pb_pin_fixup --verbose
+
+# Apply fix-up to Look-Up Table truth tables based on packing results
+lut_truth_table_fixup
+
+# Build the module graph
+#  - Enabled compression on routing architecture modules
+#  - Enabled frame view creation to save runtime and memory
+#    Note that this is turned on when bitstream generation 
+#    is the ONLY purpose of the flow!!!
+build_fabric --compress_routing --frame_view #--verbose
+
+# Repack the netlist to physical pbs
+# This must be done before bitstream generator and testbench generation
+# Strongly recommend it is done after all the fix-up have been applied
+repack #--verbose
+
+# Build the bitstream
+#  - Output the fabric-independent bitstream to a file
+build_architecture_bitstream --verbose --write_file fabric_independent_bitstream.xml
+
+# Build fabric-dependent bitstream
+build_fabric_bitstream --verbose 
+
+# Write fabric-dependent bitstream
+write_fabric_bitstream --file fabric_bitstream.txt --format plain_text
+write_fabric_bitstream --file fabric_bitstream.xml --format xml
+
+# Report bitstream distribution to a file
+report_bitstream_distribution ${OPENFPGA_REPORT_BITSTREAM_DISTRIBUTION_OPTIONS}
+
+# Finish and exit OpenFPGA
+exit
+
+# Note :
+# To run verification at the end of the flow maintain source in ./SRC directory

openfpga_flow/regression_test_scripts/fpga_bitstream_reg_test.sh

@@ -28,3 +28,7 @@ run-task fpga_bitstream/overload_mux_default_path --debug --show_thread_logs
 
 echo -e "Testing outputting I/O mapping result to file";
 run-task fpga_bitstream/write_io_mapping --debug --show_thread_logs
+
+echo -e "Testing report bitstream distribution to file";
+run-task fpga_bitstream/report_bitstream_distribution/default_depth --debug --show_thread_logs
+run-task fpga_bitstream/report_bitstream_distribution/custom_depth --debug --show_thread_logs

openfpga_flow/tasks/fpga_bitstream/report_bitstream_distribution/custom_depth/config/task.conf

@@ -0,0 +1,33 @@
+# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+# Configuration file for running experiments
+# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+# timeout_each_job : FPGA Task script splits fpga flow into multiple jobs
+# Each job execute fpga_flow script on combination of architecture & benchmark
+# timeout_each_job is timeout for each job
+# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+
+[GENERAL]
+run_engine=openfpga_shell
+power_tech_file = ${PATH:OPENFPGA_PATH}/openfpga_flow/tech/PTM_45nm/45nm.xml
+power_analysis = true
+spice_output=false
+verilog_output=true
+timeout_each_job = 20*60
+fpga_flow=yosys_vpr
+
+[OpenFPGA_SHELL]
+openfpga_shell_template=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_shell_scripts/report_bitstream_distribution_example_script.openfpga
+openfpga_arch_file=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_arch/k6_frac_N10_40nm_openfpga.xml
+openfpga_sim_setting_file=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_simulation_settings/auto_sim_openfpga.xml
+openfpga_report_bitstream_distribution_options=--file bitstream_distribution.xml --depth 2
+
+[ARCHITECTURES]
+arch0=${PATH:OPENFPGA_PATH}/openfpga_flow/vpr_arch/k6_frac_N10_tileable_40nm.xml
+
+[BENCHMARKS]
+bench0=${PATH:OPENFPGA_PATH}/openfpga_flow/benchmarks/micro_benchmark/and2/and2.v
+
+[SYNTHESIS_PARAM]
+bench0_top = and2
+
+[SCRIPT_PARAM_MIN_ROUTE_CHAN_WIDTH]

openfpga_flow/tasks/fpga_bitstream/report_bitstream_distribution/default_depth/config/task.conf

@@ -0,0 +1,33 @@
+# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+# Configuration file for running experiments
+# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+# timeout_each_job : FPGA Task script splits fpga flow into multiple jobs
+# Each job execute fpga_flow script on combination of architecture & benchmark
+# timeout_each_job is timeout for each job
+# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+
+[GENERAL]
+run_engine=openfpga_shell
+power_tech_file = ${PATH:OPENFPGA_PATH}/openfpga_flow/tech/PTM_45nm/45nm.xml
+power_analysis = true
+spice_output=false
+verilog_output=true
+timeout_each_job = 20*60
+fpga_flow=yosys_vpr
+
+[OpenFPGA_SHELL]
+openfpga_shell_template=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_shell_scripts/report_bitstream_distribution_example_script.openfpga
+openfpga_arch_file=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_arch/k6_frac_N10_40nm_openfpga.xml
+openfpga_sim_setting_file=${PATH:OPENFPGA_PATH}/openfpga_flow/openfpga_simulation_settings/auto_sim_openfpga.xml
+openfpga_report_bitstream_distribution_options=--file bitstream_distribution.xml
+
+[ARCHITECTURES]
+arch0=${PATH:OPENFPGA_PATH}/openfpga_flow/vpr_arch/k6_frac_N10_tileable_40nm.xml
+
+[BENCHMARKS]
+bench0=${PATH:OPENFPGA_PATH}/openfpga_flow/benchmarks/micro_benchmark/and2/and2.v
+
+[SYNTHESIS_PARAM]
+bench0_top = and2
+
+[SCRIPT_PARAM_MIN_ROUTE_CHAN_WIDTH]