Add memory boundary test

- Added unit tests to CI workflow.
- Added Dockerfile for testing environment setup.
- Created `TESTING.md` for guidelines on running tests.
- Implemented memory boundary test in `tests/memory_boundary_test.cpp` with CMake configuration.

Author: cphurley82

.github/workflows/ci-transaction_recording.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    paths:
+      - '**.cpp'
+      - '**.h'
+      - '**CMakeLists.txt'
+      - 'tests/**'
+      - '.github/workflows/**'
+  pull_request:
+    paths:
+      - '**.cpp'
+      - '**.h'
+      - '**CMakeLists.txt'
+      - 'tests/**'
+      - '.github/workflows/**'
+
+jobs:
+  unit-tests:
+    name: unit-tests (C++20)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache Conan
+        uses: actions/cache@v4
+        with:
+          path: ~/.conan
+          key: conan-${{ runner.os }}-unit-cpp20-${{ hashFiles('conanfile.txt') }}
+
+      - name: Update submodules
+        run: git submodule update --init --recursive
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake g++ python3-pip
+          pip3 install "conan<2.0"
+
+      - name: Configure
+        run: >
+          cmake -S . -B build
+          -DBUILD_TESTING=ON
+          -DCMAKE_CXX_STANDARD=20
+
+      - name: Build
+        run: cmake --build build -j
+
+      - name: Run unit tests
+        run: ctest --output-on-failure
+        working-directory: build
+
+  txrec:
+    name: txrec (C++${{ matrix.cpp_std }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        cpp_std: [11, 14, 17, 20]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache Conan
+        uses: actions/cache@v4
+        with:
+          path: ~/.conan
+          key: conan-${{ runner.os }}-txrec-cpp${{ matrix.cpp_std }}-${{ hashFiles('conanfile.txt') }}
+
+      - name: Update submodules
+        run: git submodule update --init --recursive
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake g++ python3-pip
+          pip3 install "conan<2.0"
+
+      - name: Configure
+        run: >
+          cmake -S . -B build
+          -DBUILD_TESTING=OFF
+          -DCMAKE_CXX_STANDARD=${{ matrix.cpp_std }}
+
+      - name: Build
+        run: cmake --build build -j
+
+      - name: Run transaction_recording example
+        run: ./build/examples/transaction_recording/transaction_recording

.github/workflows/ci.yml

@@ -7,6 +7,7 @@ project(scc VERSION 2025.09 LANGUAGES CXX C)
 option(USE_CWR_SYSTEMC "Use Synopsys Virtualizer SystemC" OFF)
 option(USE_NCSC_SYSTEMC "Cadence Xcelium SystemC" OFF)
 option(ENABLE_CONAN "Enable the use of conan in standalone build" ON)
+option(BUILD_TESTING "Enable building tests" OFF)
 option(BUILD_SCC_DOCUMENTATION "Create and install the HTML based API documentation (requires Doxygen)" OFF)
 option(FULL_TRACE_TYPE_LIST "Test for extended set of templated datatypes" OFF)
 #Note: this needs to match the SystemC kernel build options
@@ -44,6 +45,9 @@ if(CMAKE_PROJECT_NAME STREQUAL "scc")
             # Boost on CentOS quirks end
         endif()
         set(CONAN_PACKAGE_LIST jsoncpp/1.9.5 yaml-cpp/0.6.3 spdlog/1.9.2 fmt/8.0.1 zlib/1.2.12 lz4/1.9.4 boost/1.75.0)
+        if(BUILD_TESTING)
+            list(APPEND CONAN_PACKAGE_LIST gtest/1.14.0)
+        endif()
         if(BUILD_SCC_DOCUMENTATION)
             list(APPEND CONAN_PACKAGE_LIST doxygen/1.9.2)
         endif()
@@ -145,6 +149,10 @@ include(CheckSymbolExists)
 # Check for function getenv()
 check_symbol_exists(getenv "stdlib.h" HAVE_GETENV)
 
+if(BUILD_TESTING)
+    include(CTest)
+endif()
+
 if(NOT TARGET lz4::lz4)
     message(STATUS "${PROJECT_NAME}: using built-in version of lz4")
     add_subdirectory(third_party/lz4-1.9.4)
@@ -165,6 +173,10 @@ if(SystemC_FOUND)
         endif()
     endif()
 
+    if(BUILD_TESTING)
+        add_subdirectory(tests)
+    endif()
+
     # Define the scc library
     add_library(scc INTERFACE)
     add_library(scc::scc ALIAS scc)

CMakeLists.txt

@@ -0,0 +1,16 @@
+FROM ubuntu:22.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        build-essential \
+        cmake \
+        git \
+        python3 \
+        python3-pip \
+        ca-certificates && \
+    pip3 install "conan<2.0" && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /work

Dockerfile.test

@@ -0,0 +1,54 @@
+# Running Tests
+
+This repository has a GoogleTest-based suite (see `tests/`). The tests target the CMake option `BUILD_TESTING=ON` and require the same dependencies as the main build plus GoogleTest (fetched automatically via `FetchContent`).
+
+## Prerequisites
+
+- CMake ≥ 3.20
+- A C++ compiler (GCC/Clang) with C++17 or later
+- Python 3 with `conan<2.0` installed. A virtual environment is recommended:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install "conan<2.0"
+```
+
+If Conan cannot supply SystemC/CCI on your host, use the Docker flow below or point CMake at a local SystemC install via `SYSTEMC_HOME`.
+
+## Configure and Build
+
+```bash
+cmake -S . -B build -DBUILD_TESTING=ON -DCMAKE_CXX_STANDARD=20
+cmake --build build -j
+```
+
+## Run Tests
+
+```bash
+cd build
+
+# unit tests
+ctest --output-on-failure
+
+# transaction recording example binary
+./examples/transaction_recording/transaction_recording
+```
+
+## Run Tests in Docker (Linux toolchain)
+
+If your host setup cannot fetch SystemC via Conan, use the provided Dockerfile:
+
+```bash
+# from repo root
+docker build -f Dockerfile.test -t scc-tests .
+docker run --rm -v "$PWD":/work -w /work scc-tests /bin/bash -lc "\
+  cmake -S . -B build -DBUILD_TESTING=ON -DCMAKE_CXX_STANDARD=20 && \
+  cmake --build build -j && \
+  cd build && ctest --output-on-failure && \
+  ./examples/transaction_recording/transaction_recording"
+```
+
+## CI
+
+Tests run in `.github/workflows/ci.yml`, which configures with `-DBUILD_TESTING=ON`, builds, runs `ctest`, and executes the `transaction_recording` example for C++ standards 11/14/17/20.

TESTING.md

@@ -0,0 +1,15 @@
+find_package(GTest REQUIRED)
+
+add_executable(memory_boundary_test
+    memory_boundary_test.cpp
+)
+
+target_link_libraries(memory_boundary_test
+    PRIVATE
+        GTest::gtest_main
+        scc::scc
+        SystemC::systemc
+)
+target_compile_definitions(memory_boundary_test PRIVATE SC_DISABLE_API_VERSION_CHECK)
+
+add_test(NAME memory_boundary_test COMMAND memory_boundary_test)

tests/CMakeLists.txt

@@ -0,0 +1,39 @@
+// Validates that handle_operation does not overwrite past the requested length
+#include <array>
+#include <systemc>
+#include <tlm>
+#include <gtest/gtest.h>
+
+#include "components/scc/memory.h"
+#include "scc/cci_broker.h"
+
+TEST(MemoryBoundaryTest, ReadAcrossPageDoesNotOverwriteBuffer) {
+    static scc::cci_broker global_broker("global_broker");
+    static auto broker_handle = cci::cci_register_broker(&global_broker);
+    constexpr uint64_t kPageSize = 1ull << 24; // matches util::sparse_array default page size
+    scc::memory<(kPageSize + 2u)> mem{"mem"};
+
+    std::array<uint8_t, 2> write_data{{0xAAu, 0xBBu}};
+    tlm::tlm_generic_payload write;
+    sc_core::sc_time delay = sc_core::SC_ZERO_TIME;
+    write.set_command(tlm::TLM_WRITE_COMMAND);
+    write.set_address(kPageSize - 1); // straddles page boundary
+    write.set_data_length(write_data.size());
+    write.set_streaming_width(write_data.size());
+    write.set_data_ptr(write_data.data());
+    mem.handle_operation(write, delay);
+
+    std::array<uint8_t, 4> read_buf{{0xEEu, 0x00u, 0x00u, 0xEEu}};
+    tlm::tlm_generic_payload read;
+    read.set_command(tlm::TLM_READ_COMMAND);
+    read.set_address(kPageSize - 1);
+    read.set_data_length(write_data.size());
+    read.set_streaming_width(write_data.size());
+    read.set_data_ptr(read_buf.data() + 1); // leave guard bytes at both ends
+    mem.handle_operation(read, delay);
+
+    EXPECT_EQ(read_buf[0], 0xEEu);       // leading guard untouched
+    EXPECT_EQ(read_buf[1], 0xAAu);       // first byte read correctly
+    EXPECT_EQ(read_buf[2], 0xBBu);       // second byte read correctly
+    EXPECT_EQ(read_buf[3], 0xEEu);       // trailing guard must remain
+}