Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions AUTHORS
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# This is the list of Abseil authors for copyright purposes.
#
# This does not necessarily list everyone who has contributed code, since in
# some cases, their employer may be the copyright holder. To see the full list
# of contributors, see the revision history in source control.

Yu-Sheng Lin
You-Tang Lee
rfuest
22 changes: 11 additions & 11 deletions src/CMakeLists.txt → CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,7 @@ include_directories(${CMAKE_CURRENT_SOURCE_DIR})

# Collect cpp files (recursively) and split regular library sources vs tests (files ending with ".test.cpp")
file(GLOB_RECURSE FST_CPP_FILES
"${CMAKE_CURRENT_SOURCE_DIR}/fstcpp/*.cpp"
"${CMAKE_CURRENT_SOURCE_DIR}/gtkwave/*.cpp"
"fstcpp/*.cpp"
)

# Lists to populate
Expand Down Expand Up @@ -77,17 +76,18 @@ endforeach()
#######################################
# Build the integration tests for testing bit-true behavior
#######################################
# compile verilator_shared/*.cpp as an cmake object
# compile verilator_share/*.cpp as an cmake object
# Non-recursively to exclude gtkwave/ folder
file(
GLOB_RECURSE
VERILATOR_SHARED
${CMAKE_CURRENT_SOURCE_DIR}/integration_test/verilator_share/*.cpp
GLOB
VERILATOR_SHARE
integration_test/verilator_share/*.cpp
)
add_library(verilator_shared OBJECT ${VERILATOR_SHARED})
include_directories(${CMAKE_CURRENT_SOURCE_DIR}/integration_test/verilator_share)
add_library(verilator_share OBJECT ${VERILATOR_SHARE})
include_directories(integration_test/verilator_share)

# for all direct folders under integration_test/tests, find all *.cpp files and compile them as an executable
file(GLOB TEST_PATHS ${CMAKE_CURRENT_SOURCE_DIR}/integration_test/tests/*)
file(GLOB TEST_PATHS integration_test/tests/*)

foreach(TEST_PATH ${TEST_PATHS})
get_filename_component(TEST_NAME ${TEST_PATH} NAME)
Expand All @@ -98,13 +98,13 @@ foreach(TEST_PATH ${TEST_PATHS})
file(GLOB_RECURSE TEST_SRCS ${TEST_PATH}/*.cpp)

# C executable
add_executable(${TEST_NAME}_c ${TEST_SRCS} gtkwave/fstapi.c $<TARGET_OBJECTS:verilator_shared>)
add_executable(${TEST_NAME}_c ${TEST_SRCS} integration_test/verilator_share/gtkwave/fstapi.c $<TARGET_OBJECTS:verilator_share>)
target_link_libraries(${TEST_NAME}_c PRIVATE fstcpp)
target_include_directories(${TEST_NAME}_c PRIVATE ${TEST_PATH}/verilated)
add_test(NAME ${TEST_NAME}_c COMMAND ${TEST_NAME}_c ${TEST_NAME}_dump_c.fst)

# C++ executable
add_executable(${TEST_NAME}_cpp ${TEST_SRCS} gtkwave/fstapi.cpp $<TARGET_OBJECTS:verilator_shared>)
add_executable(${TEST_NAME}_cpp ${TEST_SRCS} integration_test/verilator_share/gtkwave/fstapi.cpp $<TARGET_OBJECTS:verilator_share>)
target_link_libraries(${TEST_NAME}_cpp PRIVATE fstcpp)
target_include_directories(${TEST_NAME}_cpp PRIVATE ${TEST_PATH}/verilated)
add_test(NAME ${TEST_NAME}_cpp COMMAND ${TEST_NAME}_cpp ${TEST_NAME}_dump_cpp.fst)
Expand Down
45 changes: 24 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The unittests are written in C++20.
- **C++14**: The core of this project is written in clean C++14 to maximize compatibility. Using `vector` and `string` can eliminate most resource management code compared to C.
- **High Performance**: Optimized for speed to reduce simulation overhead (2x faster than the original `fstapi` when used with Verilator). This is mainly because we process data as binary instead of strings used by the original `fstapi.c`.
- **Drop-in Compatibility**: Includes an optional C-compatible wrapper `fstapi.cpp`, providing the same writer interface as the original `fstapi.c`.
- **Robust Testing**: Comprehensive unit tests written in C++20 to ensure correctness. Coverage is also generated and checked (70% line and 70% function coverage).
- **Robust Testing**: Comprehensive unit tests written in C++20 to ensure correctness. Coverage is also generated and checked (85% line and 85% function coverage).
- **Bit-true**: The implementation is bit-true to the original `fstapi.c` (tested in unittests).

## Regression Reports (WIP due to GitHub Actions permission issue)
Expand All @@ -24,18 +24,17 @@ To view it:

## 📂 Project Structure

Every file of this project is under the `src` directory, which also includes third-party files:

```
fstcpp/ # 🌟 MAIN: Core C++ implementation
├── Writer.h # - The new C++ API header
└─── Writer.cpp # - The implementation
gtkwave/ # 📚 ORIGINAL: Original GtkWave files
├── fstapi.cpp # - C-style wrapper for backward compatibility
├── fstapi.c # - REFERENCE: the original GtkWave implementation
└── fstapi.h # - The original GtkWave header file used by both fstapi.cpp and fstapi.c
integration_test/ # 🧪 TESTS: Integration tests generated by Verilator
```
- `fstcpp/`: 🌟 MAIN Core C++ implementation, header, and unittests.
- `fstcpp_writer.h`: The new C++ API header.
- `fstcpp_writer.cpp`: The implementation.
- `integration_test/`: 🧪 TESTS Integration tests generated by Verilator.
- `verilator_share/`
- `gtkwave/`: 📚 ORIGINAL GtkWave files copied from `libfst`.
- `fstapi.cpp`: C-style wrapper for backward compatibility.
- `fstapi.c`: REFERENCE - the original GtkWave implementation.
- `fstapi.h`: The original GtkWave header file.
- other files: Copied from Verilator 5.042 runtime (slightly modified for bit-true).
- other folders: individual integration tests.

---

Expand All @@ -52,15 +51,15 @@ To configure the project with debug symbols and prepare it for *VS Code*+*clangd

```bash
# Generate build files using Ninja
cmake -G Ninja -B build/debug -DCMAKE_BUILD_TYPE=Debug src
cmake -G Ninja -B build/debug -DCMAKE_BUILD_TYPE=Debug .
```

### Manual Build for Development (No coverage test)

If you prefer running steps manually, our repository follows a very standard CMake workflow, here is an example:

```bash
cmake -G Ninja -B build/debug -DCMAKE_BUILD_TYPE=Debug src
cmake -G Ninja -B build/debug -DCMAKE_BUILD_TYPE=Debug .
cd build/debug
ninja -j$(nproc)
ctest -j$(nproc)
Expand All @@ -78,7 +77,7 @@ By default, it will create `build/regression` directory.

### Installation

There is no standard installation step now, just copy the files in `src/fstcpp` to your project. If you want to use the C-style wrapper, also copy `src/gtkwave/fstapi.cpp` and `src/gtkwave/fstapi.h` to your project.
There is no standard installation step now, just copy the `fstcpp/` folder to your project, and remove `*.test.cpp`. If you want to use the C-style wrapper, also copy `integration_test/verilator_share/gtkwave/fstapi.(cpp|h)` to your project.

The dependencies are `ZLIB` and `lz4`, which are quite easy to install on most Linux distributions.

Expand All @@ -95,14 +94,18 @@ The main source code of this repository is licensed under the **MIT License**.
See the [LICENSE](LICENSE) file for more details.

### Details
The `src` directory of this project contains a mix of original code and redistributed files:
The root directory of this project contains a mix of original code and redistributed files:

* **MIT**
* **`fstcpp/`**: The core of this project.
* **`gtkwave/`**: Redistributed from GtkWave.
* **`integration_test/`**: All SystemVerilog files and the testbench CPP files are part of this project.
* **`integration_test/*/verilated/`**: Generated by Verilator 5.042. They are derivative works and inherit the original MIT license of the SystemVerilog source.
* **`integration_test/`**: Without explicitly mentioned, all SystemVerilog files and the testbench CPP files are part of this project.
* **`verilator_share/gtkwave/`**: Redistributed from `libfst`, which is MIT license.
* **`verilator_share/gtkwave/fstapi.cpp`**: A compatibility layer wrapping this project into `libfst`'s original C-interface.
* **`*/verilated/`**: Generated by Verilator 5.042. They are derivative works and inherit the original MIT license of the SystemVerilog source.
* **LGPL v3**
* **`integration_test/verilator_shared/`**: Copied from Verilator 5.042 runtime (slightly modified for bit-true).
* **`integration_test/verilator_share/`**: Copied from Verilator 5.042 runtime (slightly modified for bit-true).
* Projects that we have cited:
* [Verilator](https://github.com/verilator/verilator/)
* [libfst](https://github.com/gtkwave/libfst/)

**AI usage notice:** The files in this repository are assisted by *Gemini 3 Pro* with *AntiGravity*.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
12 changes: 6 additions & 6 deletions run_regression.sh
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@
# --build <build_dir>, default to ./build/regression
# --coverage, default to false
# --coverage-html, default to false, autoset --coverage to true
# --coverage-line, default to 70
# --coverage-func, default to 70
# --coverage-line, default to 85
# --coverage-func, default to 85
BUILD_DIR="build/regression"
COVERAGE=0
COVERAGE_HTML=0
COVERAGE_LINE=70
COVERAGE_FUNC=70
COVERAGE_LINE=85
COVERAGE_FUNC=85
ROOT_DIR=$(pwd)
TEST_EXIT_CODE=0
while [[ "$#" -gt 0 ]]; do
Expand All @@ -32,7 +32,7 @@ function CMakeInit() {
mkdir -p "$BUILD_DIR"
local cov_opt="OFF"
if [ $COVERAGE -eq 1 ]; then cov_opt="ON"; fi
cmake -B "$BUILD_DIR" -S src -G Ninja -DENABLE_COVERAGE=$cov_opt
cmake -B "$BUILD_DIR" -S . -G Ninja -DENABLE_COVERAGE=$cov_opt
}

function BuildAndRunTests() {
Expand All @@ -44,7 +44,7 @@ function BuildAndRunTests() {
function CollectCoverage() {
if [ $COVERAGE = 1 ]; then
lcov --capture --directory . --output-file coverage.info --ignore-errors inconsistent,mismatch,empty
lcov --extract coverage.info '*/src/fstcpp/*' --output-file coverage.info --ignore-errors inconsistent,mismatch,empty
lcov --extract coverage.info '*/fstcpp/*' --output-file coverage.info --ignore-errors inconsistent,mismatch,empty
if [ $COVERAGE_HTML = 1 ]; then
genhtml coverage.info --output-directory html
fi
Expand Down