first commit

bsvbuild.sh

@@ -0,0 +1,235 @@
+#!/bin/sh
+# Copyright(c) 2022 https://github.com/WangXuan95
+#
+# function : a single useful script for running Bluespec SystemVerilog (BSV) simulation, generating simulation wave, or generating Verilog source.
+#
+# to see usage, run:
+#     sh bsvbuild.sh
+#
+
+
+# colors for print text ------------------------------------------------------------------------------------------------------------------
+error_color="\033[1;31m"                     # echo this to change print text color for Error message. (31 is red)
+note_color="\033[1;36m"                      # echo this to change print text color for Important compile note. (36 is light blue) 
+runsim_color="\033[1;33m"                    # echo this to change print text color for Simulation run print message. (33 is yellow) 
+default_color="\033[m"                       # echo this to change print text color to default color (e.g., white)
+
+
+# name of the BSV compiler ------------------------------------------------------------------------------------------------------------------
+compiler_name="bsc"
+
+
+# some default compile temporary file name 
+sim_filename="sim.out"
+sim_so_filename=$sim_filename".so"
+v_vcd_filename_default="dump.vcd"            # This is the default .vcd file generated by Verilog simulation (generated by command: ./vsim +bscvcd)
+
+
+# default top module and top file ------------------------------------------------------------------------------------------------------------------
+top_module="mkTb"                            # default top module
+top_file="Tb.bsv"                            # default top file
+
+
+# usage (help) string ------------------------------------------------------------------------------------------------------------------
+usage="\
+\n      usage: run following command under the directory which contains .bsv source file(s):          \
+\n\t        "$0" -<param> [<top_module>] [<top_file_name>]                                            \
+\n                                                                                                    \
+\n      arguments:                                                                                    \
+\n\t        -<param>:                                                                                 \
+\n\t\t          -bs  \t: run BSV simulation.                                                          \
+\n\t\t          -bw  \t: generate BSV simulation wave.                                                \
+\n\t\t          -bsw \t: run BSV simulation and generate wave.                                        \
+\n\t\t          -v   \t: generate Verilog source only.                                                \
+\n\t\t          -vs  \t: generate Verilog source and run Verilog simulation.                          \
+\n\t\t          -vw  \t: generate Verilog source and generate Verilog simulation wave.                \
+\n\t\t          -vsw \t: generate Verilog source, run Verilog simulation and generate wave.           \
+\n\t\t          -clean : remove temporary files in current directory using:                           \
+\n\t\t\t\t                 rm *.bo *.ba *.cxx *.h *.o "$sim_filename" "$sim_so_filename"              \
+\n\t        <top_module>:                                                                             \
+\n\t\t          The top level module name. optional, default is "$top_module"                         \
+\n\t        <file_name>:                                                                              \
+\n\t\t          The top level file name. optional, default is "$top_file"                             \
+\n                                                                                                    \
+\n      example:                                                                                      \
+\n\t        "$0" -vsw mkCounter Counter.bsv                                                           \
+\n                                                                                                    \
+\n      dependency:                                                                                   \
+\n\t        1. bsc : BSV compiler                                                                     \
+\n\t        2. iverilog : Verilog simulator, only for Verilog simulation                              \
+\n                                                                                                    \
+\n      The meaning of printing colors:                                                               \
+\n\t        "$error_color"1. error message"$default_color"                                            \
+\n\t        "$note_color"2. compilation commands and important notes"$default_color"                  \
+\n\t        "$runsim_color"3. simulation print, e.g., from \$display() in BSV"$default_color"         \
+\n"
+
+
+
+# parsing command-line args ------------------------------------------------------------------------------------------------------------------
+if   [ $# = 0 ]; then                        # if there are no args,
+    echo $usage                              #    print usage
+    exit                                     #    and exit
+elif [ $# = 3 ]; then                        # if there are 3 total args (user specify a top_module and a top_file),
+    top_module=$2                            #    let top_module=arg2
+    top_file=$3                              #    let top_file=arg3
+elif [ $# = 2 ]; then                        # if there are 2 total args (user specify a top_module or  a top_file),
+    tmp=$2                                   #
+    if [ ${tmp##*.}x = "bsv"x ]; then        #    if arg2 ends with ".bsv"
+        top_file=$2                          #       let top_file=arg2   , i.e., regard arg2 as top_file name
+    else                                     #    else
+        top_module=$2                        #       let top_module=arg2 , i.e., regard arg2 as top_module name
+    fi                                       #
+fi                                           #
+param=$1                                     # let param = arg1
+
+
+
+# if param=="-clean", remove compile temporary files and exit ------------------------------------------------------------------------------------------------------------------
+if [ $param = '-clean' ]; then
+    echo $note_color rm *.bo *.ba *.cxx *.h *.o $sim_filename $sim_so_filename $v_vcd_filename_default $default_color
+    rm *.bo *.ba *.cxx *.h *.o $sim_filename $sim_so_filename $v_vcd_filename_default
+    exit
+fi
+
+
+# check whether if BSV compiler exist, if not, raise Error ------------------------------------------------------------------------------------------------------------------
+$compiler_name -help > /dev/null             # try to run BSV compiler
+if [ $? -ne 0 ]; then
+    echo $error_color"Error: BSV compiler \""$compiler_name"\" not found!"$default_color
+    exit
+fi
+
+
+# print top_module name and top_file name ------------------------------------------------------------------------------------------------------------------
+echo "top module: "$note_color$top_module$default_color
+echo "top file  : "$note_color$top_file$default_color
+echo ""
+
+
+# if top_file not exist, raise Error ------------------------------------------------------------------------------------------------------------------
+if [ ! -f $top_file ]; then
+    echo $error_color"Error: "$top_file" not found!"$default_color
+    exit
+fi
+
+
+# set generated wave file name (.vcd) ------------------------------------------------------------------------------------------------------------------
+b_vcd_filename=$top_module"_bw.vcd"          # e.g., if top_module is mkTb, then generate BSV     simulation wave file name is "mkTb_bw.vcd"
+v_vcd_filename=$top_module"_vw.vcd"          # e.g., if top_module is mkTb, then generate Verilog simulation wave file name is "mkTb_vw.vcd"
+
+
+
+# this while structure do not play a roll of loop, because it break at the end of loop.
+# this just provide a way to break the while structure with a "break" statement wherever you want, so as to execute the commands after the while structure.
+while : ; do
+
+    if [ $param = '-bs' ] || [ $param = '-bw' ] || [ $param = '-bsw' ]; then   # ------------------------------------------------------------------------------------------------------------------
+
+        # compile BSV to objects
+        echo $note_color$compiler_name -sim -g $top_module -u $top_file $default_color
+        $compiler_name -sim -g $top_module -u $top_file
+        if [ $? -ne 0 ]; then
+            echo $error_color"Error: failed to compile!"$default_color
+            break
+        fi
+
+        # link objects into a Bluespec simulation executable file
+        echo $note_color$compiler_name -sim -e $top_module -o $sim_filename $default_color
+        $compiler_name -sim -e $top_module -o $sim_filename
+        if [ $? -ne 0 ]; then
+            echo $error_color"Error: failed to link!"$default_color
+            break
+        fi
+        rm *.bo *.ba *.cxx *.h *.o
+        if [ ! -f $sim_filename ]; then
+            echo $error_color"Error: failed to generate "$sim_filename" !"$default_color
+            break
+        fi
+
+        # run simulation
+        echo $note_color
+        if   [ $param = '-bw' ]; then
+            echo ./$sim_filename -V $b_vcd_filename $runsim_color
+            ./$sim_filename -V $b_vcd_filename  > /dev/null
+        elif [ $param = '-bsw' ]; then
+            echo ./$sim_filename -V $b_vcd_filename $runsim_color
+            ./$sim_filename -V $b_vcd_filename
+        else
+            echo ./$sim_filename $runsim_color
+            ./$sim_filename
+        fi
+        echo $default_color
+
+        # check whether if wave file exist
+        if [ $param = '-bw' ] || [ $param = '-bsw' ]; then
+            if [ ! -f $b_vcd_filename ]; then
+                echo $error_color"Error: failed to generated wave file: "$b_vcd_filename" !"$default_color
+            else 
+                echo "generated wave file: "$note_color$b_vcd_filename$default_color
+            fi
+        fi
+
+    elif [ $param = '-v' ] || [ $param = '-vs' ] || [ $param = '-vw' ] || [ $param = '-vsw' ]; then   # ------------------------------------------------------------------------------------------------------------------
+
+        # compile BSV to Verilog
+        echo $note_color$compiler_name -verilog -g $top_module -u $top_file $default_color
+        $compiler_name -verilog -g $top_module -u $top_file
+        if [ $? -ne 0 ]; then
+            echo $error_color"Error: failed to generate Verilog !"$default_color
+            break
+        fi
+
+        # if param="-v" , only need to generate verilog source, exit now
+        if [ $param = '-v' ]; then 
+            break
+        fi
+
+        # link Verilog into a simulation executable file
+        echo $note_color$compiler_name -verilog -e $top_module -o $sim_filename -vsim iverilog $top_module".v" $default_color
+        $compiler_name -verilog -e $top_module -o $sim_filename -vsim iverilog $top_module".v"
+        if [ $? -ne 0 ]; then
+            echo $error_color"Error: failed to link Verilog source(s)!"$default_color
+            break
+        fi
+        if [ ! -f $sim_filename ]; then
+            echo $error_color"Error: failed to generate "$sim_filename" !"$default_color
+            break
+        fi
+
+        # run simulation
+        echo $note_color
+        if   [ $param = '-vw' ]; then
+            echo ./$sim_filename +bscvcd $runsim_color
+            ./$sim_filename +bscvcd  > /dev/null
+        elif [ $param = '-vsw' ]; then
+            echo ./$sim_filename +bscvcd $runsim_color
+            ./$sim_filename +bscvcd
+        else 
+            echo ./$sim_filename $runsim_color
+            ./$sim_filename
+        fi
+        echo $default_color
+
+        # check whether if wave file exist
+        if [ $param = '-vw' ] || [ $param = '-vsw' ]; then
+            if [ ! -f $v_vcd_filename_default ]; then
+                echo $error_color"Error: failed to generated wave file!"$default_color
+            else
+                mv $v_vcd_filename_default $v_vcd_filename
+                echo "generated wave file: "$note_color$v_vcd_filename$default_color
+            fi
+        fi
+
+    else    # --------------------------------------------------------------------------------------------------------------------------------------------
+        echo $error_color"Error: invalid argument: "$param$default_color
+        exit
+    fi
+
+    break
+done
+
+
+# previous while structure break to here
+# clean anyway, remove all compile temporary files.
+rm *.bo *.ba *.cxx *.h *.o $sim_filename $sim_so_filename $v_vcd_filename_default  >/dev/null  2>/dev/null

src/1.Hello/Hello.bsv

@@ -0,0 +1,14 @@
+// 功能：Hello World
+// 目的：演示单模块项目组织方式
+
+package Hello;       // 包名: Hello。每个.bsv文件内只能有1个同名包
+
+module mkTb();       // 模块名: mkTb
+   rule hello;                   // rule 名: hello
+      $display("Hello World!");  // 就像 Verilog 的 $display 那样，
+                                 // 该语句不参与综合, 只是在仿真时打印
+      $finish;                   // 仿真程序退出
+   endrule
+endmodule
+
+endpackage

src/10.RuleNoConflict/ConflictFree.bsv

@@ -0,0 +1,40 @@
+// usage of conflict_free
+
+package ConflictFree;
+
+module mkTb ();
+   Reg#(int) cnt <- mkReg(0);
+
+   rule up_counter;
+      cnt <= cnt + 1;
+      if(cnt > 5) $finish;
+   endrule
+
+   Reg#(int) x <- mkReg(1);
+   Reg#(int) y <- mkReg(0);
+   Reg#(int) z <- mkReg(0);
+
+   // A. 先试试不加任何属性
+   //(* mutually_exclusive = "test1, test2" *)  // B.再试试 mutually_exclusive ，发现会报运行时 Warning，因为 test1 和 test2 会同时执行
+   (* conflict_free = "test1, test2" *)       // C.最后试试 conflict_free ，发现运行时不会报 Warning 了
+
+   // test1 和 test2 能同时激活，但它们中会引起冲突的语句 x<=x+1 和 x<=x-1 不会同时执行，因为 if 语句。
+
+   rule test1;
+      y <= y + 1;      // 无关语句
+      if(cnt < 3)
+         x <= x + 1;   // 产生冲突的语句
+   endrule
+
+   rule test2;
+      z <= z + 2;      // 无关语句
+      if(cnt > 3)
+         x <= x - 1;   // 产生冲突的语句
+   endrule
+
+   rule show;
+      $display("x=%1d  y=%1d  z=%1d", x, y, z);
+   endrule
+endmodule
+
+endpackage

src/10.RuleNoConflict/MutuallyExclusive.bsv

@@ -0,0 +1,32 @@
+// usage of mutually_exclusive
+
+package MutuallyExclusive;
+
+module mkTb ();
+   Reg#(Bit#(32)) cnt <- mkReg(1);
+
+   rule up_counter;
+      cnt <= cnt << 1;
+      if(cnt > 10) $finish;
+   endrule
+
+   Reg#(int) x <- mkReg(1);
+
+   // 用 mutually_exclusive 告诉编译器 test1 和 test2 互斥
+   (* mutually_exclusive = "test1, test2" *)
+
+   // test1 和 test2 实际上是互斥的，但编译器分析不出来
+   rule test1 (cnt[1] == 1);     
+      x <= x + 1;
+   endrule
+
+   rule test2 (cnt[2] == 1);
+      x <= x - 1;
+   endrule
+
+   rule show;
+      $display("x=%1d", x);
+   endrule
+endmodule
+
+endpackage

src/11.RulePreempts/Test1.bsv

@@ -0,0 +1,38 @@
+package Test1;
+
+module mkTb ();
+
+   Reg#(Bit#(32)) cnt <- mkReg(0);
+
+   rule up_counter;
+      cnt <= cnt + 1;
+      if(cnt > 8) $finish;
+   endrule
+
+   Reg#(int) x <- mkReg(0);
+   Reg#(int) y <- mkReg(0);
+   Reg#(int) z <- mkReg(0);
+
+   // divide3, divide2, other 并不冲突，但强制给它们加上冲突：
+   // 当 divide3 激活或 divide2 激活（或者都激活）时，other 不能激活
+   (* preempts = "(divide3, divide2), other" *)
+
+   rule divide3 (cnt%3 == 0);
+      x <= x + 1;
+   endrule
+
+   rule divide2 (cnt%2 == 0);
+      y <= y + 1;
+   endrule
+
+   rule other;
+      z <= z + 1;
+   endrule
+
+   rule show;
+      $display("cnt=%1d  x=%1d  y=%1d  z=%1d", cnt, x, y, z);
+   endrule
+
+endmodule
+
+endpackage