cxxrtl: reorganize runtime component files.

In preparation for substantial expansion of CXXRTL's runtime, this commit
reorganizes the files used by the implementation. Only minimal changes are
required in a consumer.

First, change:
  -I$(yosys-config --datdir)/include
to:
  -I$(yosys-config --datdir)/include/backends/cxxrtl/runtime

Second, change:
  #include <backends/cxxrtl/cxxrtl.h>
to:
  #include <cxxrtl/cxxrtl.h>
(and do the same for cxxrtl_vcd.h, etc.)

Makefile

@@ -647,12 +647,12 @@ $(eval $(call add_include_file,frontends/ast/ast.h))
 $(eval $(call add_include_file,frontends/ast/ast_binding.h))
 $(eval $(call add_include_file,frontends/blif/blifparse.h))
 $(eval $(call add_include_file,backends/rtlil/rtlil_backend.h))
-$(eval $(call add_include_file,backends/cxxrtl/cxxrtl.h))
-$(eval $(call add_include_file,backends/cxxrtl/cxxrtl_vcd.h))
-$(eval $(call add_include_file,backends/cxxrtl/cxxrtl_capi.cc))
-$(eval $(call add_include_file,backends/cxxrtl/cxxrtl_capi.h))
-$(eval $(call add_include_file,backends/cxxrtl/cxxrtl_vcd_capi.cc))
-$(eval $(call add_include_file,backends/cxxrtl/cxxrtl_vcd_capi.h))
+$(eval $(call add_include_file,backends/cxxrtl/runtime/cxxrtl/cxxrtl.h))
+$(eval $(call add_include_file,backends/cxxrtl/runtime/cxxrtl/cxxrtl_vcd.h))
+$(eval $(call add_include_file,backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.cc))
+$(eval $(call add_include_file,backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.h))
+$(eval $(call add_include_file,backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi_vcd.cc))
+$(eval $(call add_include_file,backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi_vcd.h))
 
 OBJS += kernel/driver.o kernel/register.o kernel/rtlil.o kernel/log.o kernel/calc.o kernel/yosys.o
 OBJS += kernel/binding.o

backends/cxxrtl/cxxrtl_backend.cc

@@ -2536,7 +2536,7 @@ struct CxxrtlWorker {
 			f << "#define " << include_guard << "\n";
 			f << "\n";
 			if (top_module != nullptr && debug_info) {
-				f << "#include <backends/cxxrtl/cxxrtl_capi.h>\n";
+				f << "#include <cxxrtl/capi/cxxrtl_capi.h>\n";
 				f << "\n";
 				f << "#ifdef __cplusplus\n";
 				f << "extern \"C\" {\n";
@@ -2554,7 +2554,7 @@ struct CxxrtlWorker {
 			}
 			f << "#ifdef __cplusplus\n";
 			f << "\n";
-			f << "#include <backends/cxxrtl/cxxrtl.h>\n";
+			f << "#include <cxxrtl/cxxrtl.h>\n";
 			f << "\n";
 			f << "using namespace cxxrtl;\n";
 			f << "\n";
@@ -2573,17 +2573,17 @@ struct CxxrtlWorker {
 		if (split_intf)
 			f << "#include \"" << intf_filename << "\"\n";
 		else
-			f << "#include <backends/cxxrtl/cxxrtl.h>\n";
+			f << "#include <cxxrtl/cxxrtl.h>\n";
 		if (has_prints)
 			f << "#include <iostream>\n";
 		f << "\n";
 		f << "#if defined(CXXRTL_INCLUDE_CAPI_IMPL) || \\\n";
 		f << "    defined(CXXRTL_INCLUDE_VCD_CAPI_IMPL)\n";
-		f << "#include <backends/cxxrtl/cxxrtl_capi.cc>\n";
+		f << "#include <cxxrtl/capi/cxxrtl_capi.cc>\n";
 		f << "#endif\n";
 		f << "\n";
 		f << "#if defined(CXXRTL_INCLUDE_VCD_CAPI_IMPL)\n";
-		f << "#include <backends/cxxrtl/cxxrtl_vcd_capi.cc>\n";
+		f << "#include <cxxrtl/capi/cxxrtl_capi_vcd.cc>\n";
 		f << "#endif\n";
 		f << "\n";
 		f << "using namespace cxxrtl_yosys;\n";

backends/cxxrtl/runtime/README.txt

@@ -0,0 +1,18 @@
+This directory contains the runtime components of CXXRTL and should be placed on the include path
+when building the simulation using the `-I${YOSYS}/backends/cxxrtl/runtime` option. These components
+are not used in the Yosys binary; they are only built as a part of the simulation binary.
+
+The interfaces declared in `cxxrtl_capi*.h` contain the stable C API. These interfaces will not be
+changed in backward-incompatible ways unless no other option is available, and any breaking changes
+will be made in a way that causes the downstream code to fail in a visible way. The ABI of these
+interfaces is considered stable as well, and it will not use features complicating its use via
+libraries such as libffi or ctypes.
+
+The implementations in `cxxrtl_capi*.cc` are considered private; they are still placed in the include
+path to enable build-system-less builds (where the CXXRTL runtime component is included in the C++
+file of the simulation toplevel).
+
+The interfaces declared in `cxxrtl*.h` (without `capi`) are unstable and may change without notice.
+
+For clarity, all of the files in this directory and its subdirectories have unique names regardless
+of the directory where they are placed.

backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi.cc

@@ -16,10 +16,10 @@
  *
  */
 
-// This file is a part of the CXXRTL C API. It should be used together with `cxxrtl_capi.h`.
+// This file is a part of the CXXRTL C API. It should be used together with `cxxrtl/capi/cxxrtl_capi.h`.
 
-#include <backends/cxxrtl/cxxrtl.h>
-#include <backends/cxxrtl/cxxrtl_capi.h>
+#include <cxxrtl/capi/cxxrtl_capi.h>
+#include <cxxrtl/cxxrtl.h>
 
 struct _cxxrtl_handle {
 	std::unique_ptr<cxxrtl::module> module;

backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi_vcd.cc

@@ -16,10 +16,10 @@
  *
  */
 
-// This file is a part of the CXXRTL C API. It should be used together with `cxxrtl_vcd_capi.h`.
+// This file is a part of the CXXRTL C API. It should be used together with `cxxrtl/capi/cxxrtl_capi_vcd.h`.
 
-#include <backends/cxxrtl/cxxrtl_vcd.h>
-#include <backends/cxxrtl/cxxrtl_vcd_capi.h>
+#include <cxxrtl/capi/cxxrtl_capi_vcd.h>
+#include <cxxrtl/cxxrtl_vcd.h>
 
 extern const cxxrtl::debug_items &cxxrtl_debug_items_from_handle(cxxrtl_handle handle);
 

backends/cxxrtl/runtime/cxxrtl/capi/cxxrtl_capi_vcd.h

@@ -16,8 +16,8 @@
  *
  */
 
-#ifndef CXXRTL_VCD_CAPI_H
-#define CXXRTL_VCD_CAPI_H
+#ifndef CXXRTL_CAPI_VCD_H
+#define CXXRTL_CAPI_VCD_H
 
 // This file is a part of the CXXRTL C API. It should be used together with `cxxrtl_vcd_capi.cc`.
 //
@@ -27,7 +27,7 @@
 #include <stddef.h>
 #include <stdint.h>
 
-#include <backends/cxxrtl/cxxrtl_capi.h>
+#include <cxxrtl/capi/cxxrtl_capi.h>
 
 #ifdef __cplusplus
 extern "C" {

backends/cxxrtl/runtime/cxxrtl/cxxrtl.h

@@ -39,7 +39,8 @@
 #include <functional>
 #include <sstream>
 
-#include <backends/cxxrtl/cxxrtl_capi.h>
+// `cxxrtl::debug_item` has to inherit from `cxxrtl_object` to satisfy strict aliasing requirements.
+#include <cxxrtl/capi/cxxrtl_capi.h>
 
 #ifndef __has_attribute
 #	define __has_attribute(x) 0

backends/cxxrtl/runtime/cxxrtl/cxxrtl_vcd.h

@@ -19,7 +19,7 @@
 #ifndef CXXRTL_VCD_H
 #define CXXRTL_VCD_H
 
-#include <backends/cxxrtl/cxxrtl.h>
+#include <cxxrtl/cxxrtl.h>
 
 namespace cxxrtl {
 

tests/fmt/run-test.sh

@@ -51,7 +51,7 @@ test_cxxrtl () {
 	local subtest=$1; shift
 
 	../../yosys -p "read_verilog ${subtest}.v; proc; clean; write_cxxrtl -print-output std::cerr yosys-${subtest}.cc"
-	${CC:-gcc} -std=c++11 -o yosys-${subtest} -I../.. ${subtest}_tb.cc -lstdc++
+	${CC:-gcc} -std=c++11 -o yosys-${subtest} -I../../backends/cxxrtl/runtime ${subtest}_tb.cc -lstdc++
 	./yosys-${subtest} 2>yosys-${subtest}.log
 	iverilog -o iverilog-${subtest} ${subtest}.v ${subtest}_tb.v
 	./iverilog-${subtest} |grep -v '\$finish called' >iverilog-${subtest}.log
@@ -69,7 +69,7 @@ diff iverilog-always_full.log iverilog-always_full-1.log
 
 ../../yosys -p "read_verilog display_lm.v" >yosys-display_lm.log
 ../../yosys -p "read_verilog display_lm.v; write_cxxrtl yosys-display_lm.cc"
-${CC:-gcc} -std=c++11 -o yosys-display_lm_cc -I../.. display_lm_tb.cc -lstdc++
+${CC:-gcc} -std=c++11 -o yosys-display_lm_cc -I../../backends/cxxrtl/runtime display_lm_tb.cc -lstdc++
 ./yosys-display_lm_cc >yosys-display_lm_cc.log
 for log in yosys-display_lm.log yosys-display_lm_cc.log; do
 	grep "^%l: \\\\bot\$" "$log"