Merge pull request #1663 from antmicro/eblif_params

EBLIF cell parameter interpretation

Author: vaughnbetz

doc/src/vpr/file_formats.rst

@@ -391,17 +391,36 @@ The ``.param`` statement allows parameters (e.g. primitive modes) to be tagged o
 
 .. note:: ``.param`` statements apply to the previous primitive instantiation.
 
+Parameters can have one of the three available types. Type is inferred from the format in which a parameter is provided.
+
+ * **string**
+    Whenever a parameter value is quoted it is considered to be a string. BLIF parser does not allow escaped characters hence those are illegal and will cause syntax errors.
+
+ * **binary word**
+    Binary words are specified using strings of characters ``0`` and ``1``. No other characters are allowed. Number of characters denotes the word length.
+
+ * **real number**
+    Real numbers are stored as decimals where the dot ``.`` character separates the integer and fractional part. Presence of the dot character implies that the value is to be treated as a real number.
+
 For example:
 
 .. code-block:: none
 
-    .subckt dsp a=a_in b=b_in cin=c_in cout=c_out s=sum_out
-    .param mode adder
+    .subckt pll clk_in=gclk clk_out=pclk
+    .param feedback "internal"
+    .param multiplier 0.50
+    .param power 001101
 
-Would set the parameter ``mode`` of the above ``dsp`` ``.subckt`` to ``adder``.
+Would set the parameters ``feedback``, ``multiplier`` and ``power``  of the above ``pll`` ``.subckt`` to ``"internal"``, ``0.50`` and ``001101`` respectively.
+
+.. warning:: Integers in notation other than binary (e.g. decimal, hexadecimal) are not supported. Occurrence of params with digits other than 1 and 0 for binary words, not quoted (strings) or not separated with dot ``.`` (real numbers) are considered to be illegal.
+
+Interpretation of parameter values is out of scope of the BLIF format extension.
 
 ``.param`` statements propagate to ``<parameter>`` elements in the packed netlist.
 
+Paramerer values propagate also to the post-route Verilog netlist, if it is generated. Strings and real numbers are passed directly while binary words are prepended with the ``<N>'b`` prefix where ``N`` denotes a binary word length.
+
 .attr
 ~~~~~
 The ``.attr`` statement allows attributes (e.g. source file/line) to be tagged on BLIF primitives.

vpr/src/base/netlist_writer.cpp

@@ -20,6 +20,8 @@
 #include "vpr_error.h"
 #include "vpr_types.h"
 
+#include "read_blif.h"
+
 #include "netlist_walker.h"
 #include "netlist_writer.h"
 
@@ -625,7 +627,13 @@ class BlackBoxInst : public Instance {
 
         //Verilog parameters
         for (auto iter = params_.begin(); iter != params_.end(); ++iter) {
-            os << indent(depth + 1) << "." << iter->first << "(" << iter->second << ")";
+            /* Prepend a prefix if needed */
+            std::stringstream prefix;
+            if (is_binary_param(iter->second)) {
+                prefix << iter->second.length() << "'b";
+            }
+
+            os << indent(depth + 1) << "." << iter->first << "(" << prefix.str() << iter->second << ")";
             if (iter != --params_.end()) {
                 os << ",";
             }

vpr/src/base/read_blif.cpp

@@ -20,6 +20,8 @@
 #include <sstream>
 #include <unordered_set>
 #include <cctype> //std::isdigit
+#include <algorithm>
+#include <regex>
 
 #include "blifparse.hpp"
 #include "atom_netlist.h"
@@ -386,6 +388,14 @@ struct BlifAllocCallback : public blifparse::Callback {
             parse_error(lineno_, ".param", "Supported only in extended BLIF format");
         }
 
+        // Validate the parameter value
+        bool is_valid = is_string_param(value) || is_binary_param(value) || is_real_param(value);
+
+        if (!is_valid) {
+            std::string msg = "Incorrect parameter '" + name + "' value specification. Value '" + value + "' is not recognized as string, binary word or real number. Possible causes:\n\t* lack or inconsistency in quotes (string)\n\t* no dot '.' to separate integer and fractional part (real number)\n\t* use of characters other than '1' and '0' (binary word)";
+            parse_error(lineno_, ".param", msg);
+        }
+
         curr_model().set_block_param(curr_block(), name, value);
     }
 
@@ -666,6 +676,67 @@ vtr::LogicValue to_vtr_logic_value(blifparse::LogicValue val) {
     return new_val;
 }
 
+bool is_string_param(const std::string& param) {
+    /* Empty param is considered a string */
+    if (param.empty()) {
+        return true;
+    }
+
+    /* There have to be at least 2 characters (the quotes) */
+    if (param.length() < 2) {
+        return false;
+    }
+
+    /* The first and the last characters must be quotes */
+    size_t len = param.length();
+    if (param[0] != '"' || param[len - 1] != '"') {
+        return false;
+    }
+
+    /* There mustn't be any other quotes except for escaped ones */
+    for (size_t i = 1; i < (len - 1); ++i) {
+        if (param[i] == '"' && param[i - 1] != '\\') {
+            return false;
+        }
+    }
+
+    /* This is a string param */
+    return true;
+}
+
+bool is_binary_param(const std::string& param) {
+    /* Must be non-empty */
+    if (param.empty()) {
+        return false;
+    }
+
+    /* The string must contain only '0' and '1' */
+    for (size_t i = 0; i < param.length(); ++i) {
+        if (param[i] != '0' && param[i] != '1') {
+            return false;
+        }
+    }
+
+    /* This is a binary word param */
+    return true;
+}
+
+bool is_real_param(const std::string& param) {
+    /* Must be non-empty */
+    if (param.empty()) {
+        return false;
+    }
+
+    /* The string must match the regular expression */
+    static const std::regex real_number_expr("[+-]?([0-9]*\\.[0-9]+)|([0-9]+\\.[0-9]*)");
+    if (!std::regex_match(param, real_number_expr)) {
+        return false;
+    }
+
+    /* This is a real number param */
+    return true;
+}
+
 AtomNetlist read_blif(e_circuit_format circuit_format,
                       const char* blif_file,
                       const t_model* user_models,

vpr/src/base/read_blif.h

@@ -4,6 +4,10 @@
 #include "atom_netlist_fwd.h"
 #include "read_circuit.h"
 
+bool is_string_param(const std::string& param);
+bool is_binary_param(const std::string& param);
+bool is_real_param(const std::string& param);
+
 AtomNetlist read_blif(e_circuit_format circuit_format,
                       const char* blif_file,
                       const t_model* user_models,

vtr_flow/benchmarks/tests/test_eblif.eblif

@@ -5,12 +5,16 @@
 .names a b a_and_b
 11 1
 .cname lut_a_and_b
-.param test_names_param "test_names_param_value"
+.param test_names_param_str "test_names_param_str_value"
+.param test_names_param_bin 00110101
+.param test_names_param_num 2.0
 .attr test_names_attrib "test_names_param_attrib"
 
 .latch a_and_b dff_q re clk 0
 .cname my_dff
-.param test_latch_param "test_latch_param_value"
+.param test_latch_param "test_latch_param_str_value"
+.param test_latch_param_bin 00110101
+.param test_latch_param_num 2.0
 .attr test_latch_attrib "test_latch_param_attrib"
 
 .conn dff_q o_dff