From b92173bf3d4025d214369c3773348622bd185c17 Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Wed, 28 Sep 2022 09:04:14 -0400 Subject: [PATCH] Add --binary option as alias of --main --exe --build (#3625). --- Changes | 1 + Makefile.in | 3 ++ bin/verilator | 2 + docs/guide/example_binary.rst | 63 +++++++++++++++++++++++++++ docs/guide/example_cc.rst | 11 +++-- docs/guide/example_dist.rst | 2 + docs/guide/example_sc.rst | 2 +- docs/guide/examples.rst | 1 + docs/guide/exe_verilator.rst | 9 ++++ examples/make_hello_binary/.gitignore | 6 +++ examples/make_hello_binary/Makefile | 49 +++++++++++++++++++++ examples/make_hello_binary/top.v | 14 ++++++ src/V3Options.cpp | 7 ++- test_regress/t/t_flag_binary.pl | 30 +++++++++++++ test_regress/t/t_flag_noop_bad.out | 2 +- 15 files changed, 195 insertions(+), 7 deletions(-) create mode 100644 docs/guide/example_binary.rst create mode 100644 examples/make_hello_binary/.gitignore create mode 100644 examples/make_hello_binary/Makefile create mode 100644 examples/make_hello_binary/top.v create mode 100755 test_regress/t/t_flag_binary.pl diff --git a/Changes b/Changes index e4bf5367b..d593a3074 100644 --- a/Changes +++ b/Changes @@ -19,6 +19,7 @@ Verilator 5.001 devel clocks are now simulated correctly (#3278, #3384). [Geza Lore, Shunyao CAD] * Support timing controls (delays, event controls in any location, wait statements) and forks. See docs for details. [Krzysztof Bieganski, Antmicro Ltd] +* Add --binary option as alias of --main --exe --build (#3625). Verilator 4.227 devel diff --git a/Makefile.in b/Makefile.in index 662a57361..a32d04619 100644 --- a/Makefile.in +++ b/Makefile.in @@ -107,6 +107,7 @@ SUBDIRS = docs src test_regress \ examples/cmake_tracing_c \ examples/cmake_tracing_sc \ examples/cmake_protect_lib \ + examples/make_hello_binary \ examples/make_hello_c \ examples/make_hello_sc \ examples/make_tracing_c \ @@ -243,6 +244,7 @@ installdata: ; for p in $(VL_INST_INC_SRCDIR_FILES) ; do \ $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \ done + $(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_binary $(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_c $(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc $(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c @@ -278,6 +280,7 @@ uninstall: -rmdir $(DESTDIR)$(pkgdatadir)/include/gtkwave -rmdir $(DESTDIR)$(pkgdatadir)/include/vltstd -rmdir $(DESTDIR)$(pkgdatadir)/include + -rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_binary -rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_c -rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc -rmdir $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c diff --git a/bin/verilator b/bin/verilator index 247b4aae9..0e5a4bc7b 100755 --- a/bin/verilator +++ b/bin/verilator @@ -244,6 +244,7 @@ Verilator - Translate and simulate SystemVerilog code using C++/SystemC verilator --help verilator --version + verilator --binary -j 0 [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so] verilator --cc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so] verilator --sc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so] verilator --lint-only -Wall [source_files.v]... @@ -282,6 +283,7 @@ detailed descriptions of these arguments. --autoflush Flush streams after all $displays --bbox-sys Blackbox unknown $system calls --bbox-unsup Blackbox unsupported language features + --binary Build model binary --build Build model executable/library after Verilation --build-dep-bin Override build dependency Verilator binary --build-jobs Parallelism for --build diff --git a/docs/guide/example_binary.rst b/docs/guide/example_binary.rst new file mode 100644 index 000000000..ba88fc3ad --- /dev/null +++ b/docs/guide/example_binary.rst @@ -0,0 +1,63 @@ +.. Copyright 2003-2022 by Wilson Snyder. +.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 + +.. _Example C++ Execution: + +Example C++ Execution +===================== + +We'll compile this SystemC example into a Verilated simulation binary. For +an example that discusses the next level of detail see :ref:`Example C++ +Execution`. + +.. include:: example_common_install.rst + +Now, let's create an example Verilog file: + +.. code-block:: bash + + mkdir test_our + cd test_our + + cat >our.v <<'EOF' + module our; + initial begin $display("Hello World"); $finish; end + endmodule + EOF + +Now we run Verilator on our little example. + +.. code-block:: bash + + verilator --binary -j 0 -Wall our.v + +Breaking this command down: + +#. :vlopt:`--binary` telling Verilator to do everything needed to create a + simulation executable. + +#. :vlopt:`-j` `0' to Verilate using use as many CPU threads as the machine + has. + +#. :vlopt:`-Wall` so Verilator has stronger lint warnings + enabled. + +#. An finally, :command:`our.v` which is our SystemVerilog design file. + +And now we run it: + +.. code-block:: bash + + obj_dir/Vour + +And we get as output: + +.. code-block:: bash + + Hello World + - our.v:2: Verilog $finish + +Really, you're better off using a Makefile to run the steps for you so when +your source changes it will automatically run all of the appropriate steps. +To aid this Verilator can create a makefile dependency file. For examples +that do this see the :file:`examples` directory in the distribution. diff --git a/docs/guide/example_cc.rst b/docs/guide/example_cc.rst index f5d55c8da..192704559 100644 --- a/docs/guide/example_cc.rst +++ b/docs/guide/example_cc.rst @@ -43,13 +43,10 @@ Now we run Verilator on our little example. .. code-block:: bash - verilator -Wall --cc --exe --build sim_main.cpp our.v + verilator --cc --exe --build -j 0 -Wall sim_main.cpp our.v Breaking this command down: -#. :vlopt:`-Wall` so Verilator has stronger lint warnings - enabled. - #. :vlopt:`--cc` to get C++ output (versus e.g. SystemC or only linting). @@ -61,6 +58,12 @@ Breaking this command down: own compile rules, and run make yourself as we show in :ref:`Example SystemC Execution`.) +#. :vlopt:`-j` `0' to Verilate using use as many CPU threads as the machine + has. + +#. :vlopt:`-Wall` so Verilator has stronger lint warnings + enabled. + #. An finally, :command:`our.v` which is our SystemVerilog design file. Once Verilator completes we can see the generated C++ code under the diff --git a/docs/guide/example_dist.rst b/docs/guide/example_dist.rst index 5b45ed1eb..6e6947071 100644 --- a/docs/guide/example_dist.rst +++ b/docs/guide/example_dist.rst @@ -10,6 +10,8 @@ See the ``examples/`` directory that is part of the distribution, and is installed (in a OS-specific place, often in e.g. ``/usr/local/share/verilator/examples``). These examples include: +examples/make_hello_binary + Example GNU-make simple Verilog->binary conversion examples/make_hello_c Example GNU-make simple Verilog->C++ conversion examples/make_hello_sc diff --git a/docs/guide/example_sc.rst b/docs/guide/example_sc.rst index ef8eb03ca..987554f81 100644 --- a/docs/guide/example_sc.rst +++ b/docs/guide/example_sc.rst @@ -43,7 +43,7 @@ Now we run Verilator on our little example: .. code-block:: bash - verilator -Wall --sc --exe sc_main.cpp our.v + verilator --sc --exe -Wall sc_main.cpp our.v This example does not use --build, therefore we need to explicitly compile it: diff --git a/docs/guide/examples.rst b/docs/guide/examples.rst index d57a82d57..b92fe9a78 100644 --- a/docs/guide/examples.rst +++ b/docs/guide/examples.rst @@ -17,6 +17,7 @@ This section covers the following examples: :maxdepth: 1 :hidden: + example_binary.rst example_cc.rst example_sc.rst example_dist.rst diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index aff59dd5b..7ced835e3 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -115,6 +115,13 @@ Summary: Using this argument will likely cause incorrect simulation. +.. option:: --binary + + Create a Verilated simulator binary. Alias for :vlopt:`--main` + :vlopt:`--exe` :vlopt:`--build`. + + See also :vlopt:`-j`. + .. option:: --build After generating the SystemC/C++ code, Verilator will invoke the @@ -780,6 +787,8 @@ Summary: Implies :vlopt:`--cc` if no other output mode was provided. + See also :vlopt:`--binary`. + .. option:: --max-num-width Set the maximum number literal width (e.g. in 1024'd22 this it the diff --git a/examples/make_hello_binary/.gitignore b/examples/make_hello_binary/.gitignore new file mode 100644 index 000000000..f68b202e1 --- /dev/null +++ b/examples/make_hello_binary/.gitignore @@ -0,0 +1,6 @@ +*.dmp +*.log +*.csrc +*.vcd +obj_* +logs diff --git a/examples/make_hello_binary/Makefile b/examples/make_hello_binary/Makefile new file mode 100644 index 000000000..19bec2dd0 --- /dev/null +++ b/examples/make_hello_binary/Makefile @@ -0,0 +1,49 @@ +###################################################################### +# +# DESCRIPTION: Verilator Example: Small Makefile +# +# This calls the object directory makefile. That allows the objects to +# be placed in the "current directory" which simplifies the Makefile. +# +# This file ONLY is placed under the Creative Commons Public Domain, for +# any use, without warranty, 2020 by Wilson Snyder. +# SPDX-License-Identifier: CC0-1.0 +# +###################################################################### +# Check for sanity to avoid later confusion + +ifneq ($(words $(CURDIR)),1) + $(error Unsupported: GNU Make cannot build in directories containing spaces, build elsewhere: '$(CURDIR)') +endif + +###################################################################### + +# This is intended to be a minimal example. Before copying this to start a +# real project, it is better to start with a more complete example, +# e.g. examples/make_tracing_c. + +# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a +# package install, and verilator is in your path. Otherwise find the +# binary relative to $VERILATOR_ROOT (such as when inside the git sources). +ifeq ($(VERILATOR_ROOT),) +VERILATOR = verilator +else +export VERILATOR_ROOT +VERILATOR = $(VERILATOR_ROOT)/bin/verilator +endif + +default: + @echo "-- Verilator hello-world simple binary example" + @echo "-- VERILATE & BUILD --------" + $(VERILATOR) --binary -j 0 top.v + @echo "-- RUN ---------------------" + obj_dir/Vtop + @echo "-- DONE --------------------" + @echo "Note: Once this example is understood, see examples/make_hello_c." + @echo "Note: See also https://verilator.org/guide/latest/examples.html" + +###################################################################### + +maintainer-copy:: +clean mostlyclean distclean maintainer-clean:: + -rm -rf obj_dir *.log *.dmp *.vpd core diff --git a/examples/make_hello_binary/top.v b/examples/make_hello_binary/top.v new file mode 100644 index 000000000..3deb48f2d --- /dev/null +++ b/examples/make_hello_binary/top.v @@ -0,0 +1,14 @@ +// DESCRIPTION: Verilator: Verilog example module +// +// This file ONLY is placed under the Creative Commons Public Domain, for +// any use, without warranty, 2017 by Wilson Snyder. +// SPDX-License-Identifier: CC0-1.0 + +// See also https://verilator.org/guide/latest/examples.html" + +module top; + initial begin + $display("Hello World!"); + $finish; + end +endmodule diff --git a/src/V3Options.cpp b/src/V3Options.cpp index 3fd6efe76..a3486a397 100644 --- a/src/V3Options.cpp +++ b/src/V3Options.cpp @@ -741,7 +741,7 @@ void V3Options::notify() { if (!outFormatOk() && v3Global.opt.main()) ccSet(); // --main implies --cc if not provided if (!outFormatOk() && !cdc() && !dpiHdrOnly() && !lintOnly() && !preprocOnly() && !xmlOnly()) { - v3fatal("verilator: Need --cc, --sc, --cdc, --dpi-hdr-only, --lint-only, " + v3fatal("verilator: Need --binary, --cc, --sc, --cdc, --dpi-hdr-only, --lint-only, " "--xml-only or --E option"); } @@ -1016,6 +1016,11 @@ void V3Options::parseOptsList(FileLine* fl, const string& optdir, int argc, char m_bboxUnsup = flag; FileLine::globalWarnOff(V3ErrorCode::E_UNSUPPORTED, true); }); + DECL_OPTION("-binary", CbCall, [this]() { + m_build = true; + m_exe = true; + m_main = true; + }); DECL_OPTION("-build", Set, &m_build); DECL_OPTION("-build-dep-bin", Set, &m_buildDepBin); DECL_OPTION("-build-jobs", CbVal, [this, fl](const char* valp) { diff --git a/test_regress/t/t_flag_binary.pl b/test_regress/t/t_flag_binary.pl new file mode 100755 index 000000000..e13118b38 --- /dev/null +++ b/test_regress/t/t_flag_binary.pl @@ -0,0 +1,30 @@ +#!/usr/bin/env perl +if (!$::Driver) { use FindBin; exec("$FindBin::Bin/bootstrap.pl", @ARGV, $0); die; } +# DESCRIPTION: Verilator: Verilog Test driver/expect definition +# +# Copyright 2019 by Wilson Snyder. This program is free software; you +# can redistribute it and/or modify it under the terms of either the GNU +# Lesser General Public License Version 3 or the Perl Artistic License +# Version 2.0. +# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 + +top_filename("t/t_flag_main.v"); + +scenarios(simulator => 1); + +compile( + verilator_flags => [# Custom as don't want -cc + "-Mdir $Self->{obj_dir}", + "--debug-check", ], + verilator_flags2 => ['--binary'], + verilator_make_cmake => 0, + verilator_make_gmake => 0, + make_main => 0, + ); + +execute( + check_finished => 1, + ); + +ok(1); +1; diff --git a/test_regress/t/t_flag_noop_bad.out b/test_regress/t/t_flag_noop_bad.out index 3f89e26a3..d7bd1b71c 100644 --- a/test_regress/t/t_flag_noop_bad.out +++ b/test_regress/t/t_flag_noop_bad.out @@ -1 +1 @@ -%Error: verilator: Need --cc, --sc, --cdc, --dpi-hdr-only, --lint-only, --xml-only or --E option +%Error: verilator: Need --binary, --cc, --sc, --cdc, --dpi-hdr-only, --lint-only, --xml-only or --E option