Makiras · Oct 22, 2026 · Oct 8, 2026 · Oct 8, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -10,8 +10,9 @@ else()
     set(XSPCOMM_PACKAGE_VERSION "${PROJECT_VERSION}")
 endif()
 
-# Increment only when the native C++ ABI becomes incompatible.
-set(XSPCOMM_ABI_VERSION 2)
+# Increment for incompatibility with master / published native ABIs.
+# Unreleased changes on this branch share one ABI transition.
+set(XSPCOMM_ABI_VERSION 3)
 
 list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
 
@@ -24,8 +25,13 @@ init_xspcomm()
 include_directories(BEFORE ${PROJECT_SOURCE_DIR}/include)
 
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lib)
-set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/include)
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lib)
+set(XSPCOMM_HEADER_STAGE ${CMAKE_CURRENT_BINARY_DIR}/include)
 
 add_subdirectory(src)
-add_subdirectory(tests)
+include(CTest)
+if(BUILD_TESTING)
+    add_subdirectory(tests)
+endif()
+add_subdirectory(integrations/tlm)
 add_subdirectory(swig)
diff --git a/Makefile b/Makefile
@@ -11,42 +11,42 @@ clean:
 	rm -rf build dist
 
 test_lua: build
-	LUA_PATH=build/lua/?.lua lua tests/test_lua.lua
+	LUA_PATH=build/lua/?.lua lua tests/bindings/lua/test_lua.lua
 
 ifeq ($(BUILD_XSPCOMM_VCS_UVMPS),)
 test_python: build
-	PYTHONPATH=build/python python3 tests/test_python.py
+	PYTHONPATH=build/python python3 tests/bindings/python/test_python.py
 
 test_java: build
-	java -cp build/java/xspcomm-java.jar tests/test_java.java
+	java -cp build/java/xspcomm-java.jar tests/bindings/java/test_java.java
 
 test_scala: build
-	scala -cp build/scala/xspcomm-scala.jar tests/test_scala.scala
+	scala -cp build/scala/xspcomm-scala.jar tests/bindings/scala/test_scala.scala
 
 test_golang: build
-	GO111MODULE=off GOPATH="`pwd`/build/golang" go run tests/test_golang.go
+	GO111MODULE=off GOPATH="`pwd`/build/golang" go run tests/bindings/golang/test_golang.go
 
 else
 test_python: build
-	LD_PRELOAD=build/lib/libuvmps_vcs.so PYTHONPATH=build/python python3 tests/test_python.py
+	LD_PRELOAD=build/lib/libuvmps_vcs.so PYTHONPATH=build/python python3 tests/bindings/python/test_python.py
 
 test_java: build
-	LD_PRELOAD=build/lib/libuvmps_vcs.so java -cp build/java/xspcomm-java.jar tests/test_java.java
+	LD_PRELOAD=build/lib/libuvmps_vcs.so java -cp build/java/xspcomm-java.jar tests/bindings/java/test_java.java
 
 test_scala: build
-	LD_PRELOAD=build/lib/libuvmps_vcs.so scala -cp build/scala/xspcomm-scala.jar tests/test_scala.scala
+	LD_PRELOAD=build/lib/libuvmps_vcs.so scala -cp build/scala/xspcomm-scala.jar tests/bindings/scala/test_scala.scala
 
 test_golang: build
-	LD_PRELOAD=build/lib/libuvmps_vcs.so GO111MODULE=off GOPATH="`pwd`/build/golang" go run tests/test_golang.go
+	LD_PRELOAD=build/lib/libuvmps_vcs.so GO111MODULE=off GOPATH="`pwd`/build/golang" go run tests/bindings/golang/test_golang.go
 
 endif
 
 test_pythird_call: build
-	cd tests && (PYTHONPATH=../build/python PYTHON_THIRD_MODUEL=test_pythirdcall python3 test_pythirdcall.py)
+	cd tests/bindings/python && (PYTHONPATH=$(CURDIR)/build/python PYTHON_THIRD_MODUEL=test_pythirdcall python3 test_pythirdcall.py)
 
 
 run: build
-	ctest --test-dir build/tests
+	ctest --test-dir build --output-on-failure
 
 rbuild: clean build run
 

diff --git a/README.cn.md b/README.cn.md
@@ -10,7 +10,7 @@ xspcomm 为 picker 的公用数据定义与操作接口，包括接口读/写、
 
 make BUILD_XSPCOMM_SWIG=python,scala,java,golang,lua
 
-# results 
+# results
 build/python/
 └── xspcomm             # python 模块
     ├── __init__.py
@@ -36,7 +36,7 @@ build/golang/
 以上示例为 Linux 下的产物形式。macOS 下原生动态库/扩展模块会保留平台原生命名（例如 `.dylib`、`.jnilib` 或模块实际文件名），不再额外拼接 Linux 风格的 `.${PROJECT_VERSION}` 后缀。
 
 **测试：**
-make命令默认编译执行 tests/test_xdata.cpp。 若要运行 tests/tests_python.py 执行如下命令：
+make命令默认编译执行 tests/unit/test_xdata.cpp。 若要运行 tests/bindings/python/test_python.py 执行如下命令：
 ```bash
 $make BUILD_XSPCOMM_SWIG=python
 $make test_python
@@ -90,7 +90,7 @@ XData(uint32_t width, IOType itype, std::string name = "");
 
 绑定DPI
 ```c++
-void BindDPIRW(xfunction<void, void *> read, 
+void BindDPIRW(xfunction<void, void *> read,
                xfunction<void, void *> write);
 void BindDPIRW(xfunction<void, void *> read,
                xfunction<void, unsigned char> write);
@@ -156,7 +156,7 @@ bool Del(std::string pin);                            // 删除引脚
 bool Connect(XPort &target);                          // 和另外一个port进行连接
 XPort &NewSubPort(std::string subprefix);             // 创建子port
 xspcomm::XData &operator[](std::string key);          // 按key获取引脚
-xspcomm::XData &Get(std::string key, 
+xspcomm::XData &Get(std::string key,
                     bool raw_key = false); // 同上
 XPort &Flip();                             // port中所有引脚值进行反转
 XPort &AsBiIO();                           // 把port中所有引脚设置为BiIO模式
@@ -286,11 +286,11 @@ if __name__ == "__main__":
 ...
 # 1 通过swig生成python wrapper
 $swig -D'MODULE_NAME="tlm_pbsb"' -python -c++ -DUSE_VCS -I${XSP_COMM_INCLUDE} \
--o tlmps.cpp ${XSP_COMM_INCLUDE}/xspcomm/python_tlm_pbsb.i
+-o tlmps.cpp ${XSP_COMM_INCLUDE}/../share/xspcomm/tlm/python.i
 
 # 2 编译通信模块
 $SYSCAN -full64 -cflags -DUSE_VCS -cflags -I{PYTHON_INCLUDE} \
--cflags -I${XSP_COMM_INCLUDE} ${XSP_COMM_INCLUDE}/xspcomm/tlm_pbsb.cpp tlmps.cpp
+-cflags -I${XSP_COMM_INCLUDE} ${XSP_COMM_INCLUDE}/../share/xspcomm/tlm/pubsub.cpp tlmps.cpp
 
 # 3 以slave模式编译 DUT
 $VLOGAN -full64 +incdir+common tlm.sv +define+UVM_OBJECT_MUST_HAVE_CONSTRUCTOR
@@ -302,7 +302,7 @@ $mv simv.daidir _tlm_pbsb.so.daidir
 ...
 ```
 
-编译完成后，可以通过 import 加载dut，具体例子请参考：tests/tlm
+编译完成后，可以通过 import 加载dut，具体例子请参考：tests/integration/tlm
 
 ### 五、其他可用接口
 
@@ -350,8 +350,6 @@ inline void XSeed(unsigned int seed)
 inline bool checkVersion()
 
 // 循环 n 次，，eg: FOR_COUNT(10){i++;}
-FOR_COUNT(n) 
+FOR_COUNT(n)
 
 ```
-
-xinstance.h 仅仅用于实例化模板类，无其他作用。
diff --git a/README.en.md b/README.en.md
@@ -11,7 +11,7 @@ Compile using the make command. Enable support for Python and other languages by
 
 make BUILD_XSPCOMM_SWIG=python,scala,java,golang,lua
 
-# results 
+# results
 build/python/
 └── xspcomm             # python module
     ├── __init__.py
@@ -37,7 +37,7 @@ build/golang/
 The example above shows Linux artifact names. On macOS, native shared libraries and extension modules keep the platform-native filename (for example `.dylib`, `.jnilib`, or the module's actual filename) instead of appending an extra Linux-style `.${PROJECT_VERSION}` suffix.
 
 **Testing:**
-The make command compiles and executes tests/test_xdata.cpp by default. To run tests/tests_python.py, execute the following commands:
+The make command compiles and executes tests/unit/test_xdata.cpp by default. To run tests/bindings/python/test_python.py, execute the following commands:
 ```bash
 $make BUILD_XSPCOMM_SWIG=python
 $make test_python
@@ -92,7 +92,7 @@ XData(uint32_t width, IOType itype, std::string name = "");
 
 Bind DPI
 ```c++
-void BindDPIRW(xfunction<void, void *> read, 
+void BindDPIRW(xfunction<void, void *> read,
                xfunction<void, void *> write);
 void BindDPIRW(xfunction<void, void *> read,
                xfunction<void, unsigned char> write);
@@ -158,7 +158,7 @@ bool Del(std::string pin);                            // Delete pin
 bool Connect(XPort &target);                          // Connect with another port
 XPort &NewSubPort(std::string subprefix);             // Create subport
 xspcomm::XData &operator[](std::string key);          // Get pin by key
-xspcomm::XData &Get(std::string key, 
+xspcomm::XData &Get(std::string key,
                     bool raw_key = false); // Same as above
 XPort &Flip();            // Flip all pin values in the port
 XPort &AsBiIO();          // Set all pins in the port to BiIO mode
@@ -290,11 +290,11 @@ Taking VCS as an example, the compilation steps of the DUT example are as follow
 ...
 # 1 Generate python wrapper through swig
 $swig -D'MODULE_NAME="tlm_pbsb"' -python -c++ -DUSE_VCS -I${XSP_COMM_INCLUDE} \
--o tlmps.cpp ${XSP_COMM_INCLUDE}/xspcomm/python_tlm_pbsb.i
+-o tlmps.cpp ${XSP_COMM_INCLUDE}/../share/xspcomm/tlm/python.i
 
 # 2 Compile the communication module
 $SYSCAN -full64 -cflags -DUSE_VCS -cflags -I{PYTHON_INCLUDE} \
--cflags -I${XSP_COMM_INCLUDE} ${XSP_COMM_INCLUDE}/xspcomm/tlm_pbsb.cpp tlmps.cpp
+-cflags -I${XSP_COMM_INCLUDE} ${XSP_COMM_INCLUDE}/../share/xspcomm/tlm/pubsub.cpp tlmps.cpp
 
 # 3 Compile DUT in slave mode
 $VLOGAN -full64 +incdir+common tlm.sv +define+UVM_OBJECT_MUST_HAVE_CONSTRUCTOR
@@ -306,7 +306,7 @@ $mv simv.daidir _tlm_pbsb.so.daidir
 ...
 ```
 
-After compilation, you can load the DUT through import. For specific examples, please refer to: tests/tlm
+After compilation, you can load the DUT through import. For specific examples, please refer to: tests/integration/tlm
 
 ### V. Other Available Interfaces
 
@@ -355,8 +355,6 @@ inline void XSeed(unsigned int seed)
 inline bool checkVersion()
 
 // Loop n times, eg: FOR_COUNT(10){i++;}
-FOR_COUNT(n) 
+FOR_COUNT(n)
 
 ```
-
-xinstance.h is only used for instantiating template classes and has no other functions.
diff --git a/cmake/Sources.cmake b/cmake/Sources.cmake
@@ -0,0 +1,28 @@
+set(XSPCOMM_SOURCES
+    common/lifetime.cpp
+    common/memory.cpp
+    monitor/callback.cpp
+    monitor/condition.cpp
+    monitor/expr.cpp
+    monitor/fsm.cpp
+    monitor/range.cpp
+    core/clock.cpp
+    core/coroutine.cpp
+    data/data.cpp
+    data/backends.cpp
+    data/value.cpp
+    data/vpi.cpp
+    data/pin.cpp
+    core/port.cpp
+    core/signal_cfg.cpp
+    core/util.cpp
+    coverage/state.cpp
+    expr/engine.cpp
+    expr/bits.cpp
+    expr/parser.cpp
+    trigger/executor.cpp
+    coverage/registration.cpp
+    runtime/engine.cpp
+    trigger/matcher.cpp
+)
+list(TRANSFORM XSPCOMM_SOURCES PREPEND "${CMAKE_CURRENT_LIST_DIR}/../src/")
diff --git a/cmake/StageHeaders.cmake b/cmake/StageHeaders.cmake
@@ -0,0 +1,6 @@
+# Build-tree staging must not retain headers removed or renamed in the source.
+file(REMOVE_RECURSE "${STAGE_INCLUDE}")
+file(MAKE_DIRECTORY "${STAGE_INCLUDE}")
+file(COPY "${SOURCE_INCLUDE}/" DESTINATION "${STAGE_INCLUDE}"
+     FILES_MATCHING PATTERN "*.h")
+file(COPY "${GENERATED_INCLUDE}/xconfig.h" DESTINATION "${STAGE_INCLUDE}")
diff --git a/cmake/xcomm.cmake b/cmake/xcomm.cmake
@@ -32,7 +32,9 @@ if(DEFINED CMAKE_BUILD_PARALLEL)
 set(INNER_CMAKE_BUILD_PARALLEL "=${CMAKE_BUILD_PARALLEL}")
 endif()
 
-set(CFLAGS "$ENV{CFLAGS} -ftls-model=global-dynamic -flto -O3 -ftree-vectorize -mtune=native -funroll-loops -funswitch-loops -fomit-frame-pointer")
+# Native signal buffers are accessed through both 32-bit and 64-bit views.
+# Keep those accesses dependent under optimization, including wheel builds.
+set(CFLAGS "$ENV{CFLAGS} -ftls-model=global-dynamic -flto -O3 -fno-strict-aliasing -ftree-vectorize -mtune=native -funroll-loops -funswitch-loops -fomit-frame-pointer")
 
 include(CheckCXXCompilerFlag)
 CHECK_CXX_COMPILER_FLAG("-std=c++20" COMPILER_SUPPORTS_CXX20)
@@ -72,8 +74,8 @@ message(STATUS "GIT_BRANCH: ${GIT_BRANCH}")
 message(STATUS "GIT_HASH: ${GIT_HASH}")
 
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/include/xspcomm/xconfig.h.in
-               ${CMAKE_CURRENT_BINARY_DIR}/include/xspcomm/xconfig.h)
-include_directories(${CMAKE_CURRENT_BINARY_DIR}/include)
+               ${CMAKE_CURRENT_BINARY_DIR}/generated/xspcomm/xconfig.h)
+include_directories(${CMAKE_CURRENT_BINARY_DIR}/generated)
 
 if (NOT "$ENV{XSPCOMM_INSTALL_PREFIX}" STREQUAL "")
   set(XSPCOMM_INSTALL_PREFIX "$ENV{XSPCOMM_INSTALL_PREFIX}" PARENT_SCOPE)