## **SUE-Sim: End-to-End Scale-Up Ethernet Simulation Platform**
Institute of Information Engineering
Chinese Academy of Sciences
State Key Laboratory of Cyberspace Security Defense
|
Institute of Microelectronics
Chinese Academy of Sciences
Artificial Intelligence Chip and System Research and Development Center
|
---
### Core Components
- **Traffic Generator**
- Continuously generates transactions according to configured data rates
- **Load Balancer**
- Balances traffic across SUE instances
- **Credit-Based Flow Control Module (CBFC)**
- Maintains credit usage for each VC to control flow
- **SUE Instance Packer**
- Opportunistically packs transactions up to preconfigured size limits
- Schedules destination queues to send transactions
- **Link-Level Retransmission Module (LLR)**
- Retransmits corrupted packets between peer devices
- **Switch**
- Implements a basic Layer 2 switch, supporting MAC address table lookup and frame forwarding
## Repository Structure
```
SUE-Sim/
├── scratch/ # Simulation scripts
│ └── SUE-Sim/ # Main simulation script and configurations
│ ├── SUE-Sim.cc # Entry point for SUE simulation
│ └── config/ # Simulation configuration files
├── src/ # ns-3 source code
│ └── sue-sim-module/ # SUE module
│ ├── model/ # Core models
│ │ ├── simulation-config/ # Simulation framework
│ │ │ ├── application-deployer.cc/.h # Application deployment
│ │ │ ├── common-utils.cc/.h # Common utility functions
│ │ │ ├── parameter-config.cc/.h # Configuration parameters
│ │ │ └── topology-builder.cc/.h # Network topology builder
│ │ ├── point-to-point-sue-net-device.cc/.h # Net device core
│ │ ├── point-to-point-sue-channel.cc/.h # P2P channel
│ │ ├── sue-cbfc.cc/.h # Credit-based flow control
│ │ ├── sue-cbfc-header.cc/.h # CBFC header
│ │ ├── sue-header.cc/.h # SUE header
│ │ ├── sue-llr.cc/.h # Link-level retransmission
│ │ ├── sue-client.cc/.h # Multi-port client
│ │ ├── sue-server.cc/.h # Unpack server
│ │ ├── sue-switch.cc/.h # Basic Layer 2 switch
│ │ ├── sue-queue-manager.cc/.h # Queue management system
│ │ ├── performance-logger.cc/.h # Performance logger
│ │ ├── traffic-generator.cc/.h # Traffic generator
│ │ ├── traffic-generator-config.cc/.h # Traffic generator configuration
│ │ ├── traffic-generator-trace.cc/.h # Trace-based traffic generator
│ │ ├── load-balancer.cc/.h # Load balancer
│ │ ├── sue-tag.cc/.h # SUE timestamp and PPP sequence tag
│ │ ├── sue-ppp-header.cc/.h # PPP header
│ │ └── sue-utils.cc/.h # SUE utility functions
│ ├── helper/ # Helper classes
│ │ └── sue-sim-module-helper.cc/.h
│ └── CMakeLists.txt # Build configuration
│
├── performance-data/ # Performance analysis results
├── log/ # Simulation logs
└── README.md # Project documentation
```
### ns-3 Version Support
**🔄 SUE-Sim supports multiple ns-3 versions**
- **ns-3 v3.44** - `main` branch
- **ns-3 v3.36** - `ns3-36` branch
## Getting Started
### Environment Requirements
- **Operating System**: Linux (Ubuntu 20.04.6 LTS)
- **Compilers**:
- **GCC**: 10.1.0+
- **Clang**: 11.0.0+
- **AppleClang**: 13.1.6+ (macOS)
- **Build Tools**:
- **CMake**: 3.13.0+ (Required)
### Installation
#### Step 1: Install System Dependencies
First, install the essential build tools and libraries:
```bash
sudo apt update
sudo apt install build-essential cmake git software-properties-common
```
#### Step 2: Check and Upgrade GCC Version
Check your current GCC version:
```bash
gcc --version
```
**If your GCC version is 10.1.0 or higher**, proceed to [Step 3](#step-3-clone-and-configure-sue-sim).
**If your GCC version is below 10.1.0** (Ubuntu 20.04 default is 9.3.0), upgrade it:
```bash
# Add Ubuntu Toolchain PPA for newer GCC versions
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt update
# Install GCC 10 and G++ 10
sudo apt install gcc-10 g++-10
# Set GCC 10 as the default compiler
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10
```
#### Step 3: Clone and Configure SUE-Sim
> **Important Note**: [This version of ns3 does not allow direct execution as root user](https://groups.google.com/g/ns-3-users/c/xDtfcaUrCwg?pli=1), please run the following commands as a regular user.
```bash
# Clone the project
git clone https://github.com/kaima2022/SUE-Sim.git
cd SUE-Sim
# Configure ns-3 environment
./ns3 configure --enable-examples --enable-tests
```
#### Step 4: Build and Verify
```bash
# Build the project
./ns3 build
# Verify installation
./ns3 run "scratch/SUE-Sim/SUE-Sim --help"
```
### Usage
The following command is the recommended basic starting point for running SUE-Sim.
#### Topology Composition
- **XPU Nodes**: 4 XPUs, each XPU contains 16 ports
- **SUE Units**: Each SUE manages 4 ports
#### Basic Run Command
```bash
./ns3 run "scratch/SUE-Sim/SUE-Sim --nXpus=4 --portsPerXpu=4 --portsPerSue=1 --enableFineGrainedMode=true --fineGrainedConfigFile=scratch/SUE-Sim/config/config.csv"
```
**Note**: NS3 logging is disabled by default. Performance data is automatically saved to `performance-data/data`.
## Configuration Parameters
SUE-Sim supports configuration parameters, covering network topology, traffic generation, link layer, CBFC flow control, and other aspects. For complete parameter descriptions, please refer to:
📋 **[Detailed Configuration Parameters Documentation](configuration.md)**
---
## Changelog
### v3.0 (2026-03-12)
- **Major Changes**:
- Added credit synchronization capability for correcting drift under packet-loss scenarios
- Added lossy switch-egress handling and improved link-layer loss recovery behavior
- Added automatic credit calibration and stronger credit-window consistency checks
- Updated routing and device-role handling to remove heuristic address mapping behavior
- Merged the per-egress-port forwarding pipeline and improved switch-side credit arbitration
- Enhanced load balancing, virtual-channel support, multi-port scheduling, and subnet allocation behavior
- Expanded performance logging and synchronized the fine-grained test inputs used by the validated scenarios
- Fixed throughput accounting and address mapping issues in the migrated implementation
- **Stability**:
- Fixed multiple bugs and optimized many implementation details
### v2.1 (2025-12-07)
- **Major Changes**:
- **State Machine Logic**: Fixed state machine logic for improved system reliability
- **Queue Scheduling**: Optimized queue scheduling algorithms
- **Credit-Based Flow Control**: Fixed credit-based flow control mechanism implementation
- **Transaction Packing**: Implemented capacity-aware transaction packing mechanism
- **Stability**:
- Fixed multiple bugs and optimized many implementation details
### v2.0 (2025-11-09)
- **Major Changes**:
- **Module Decoupling**: Decoupled various modules for better maintainability and extensibility
- **Architectural Redesign**: Rebuilt core framework with modular architecture
- **New Features**:
- **Enhanced Traffic Generation**: Added Trace-based and Configuration-based traffic generation methods
- **Advanced Logging**: Implemented comprehensive event-driven logging system
- **Performance**:
- **Event-Driven Logging**: Transformed logging statistics from fixed-time intervals to event-driven triggers
- **Code Optimization**: Optimized code logic for improved performance and readability
- **Stability**:
- **Bug Fixes**: Resolved critical issues and improved overall stability
### v1.0 (2025-10-28)
- **Initial Release**:
- Implemented basic SUE simulation framework
---
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## Contact us
For questions, suggestions, or bug reports, please feel free to contact us:
- **Kai Ma**: chasermakai@gmail.com
- **GitHub Issues**: [Submit an issue](https://github.com/kaima2022/SUE-Sim/issues)
We look forward to hearing from you and appreciate your feedback!
## Citation
If you find this project useful for your research, please consider citing it in the following format:
```bibtex
@software{SUESimulator,
month = {10},
title = {{SUE-Sim: End-to-End Scale-Up Ethernet Simulation Platform}},
url = {https://github.com/kaima2022/SUE-Sim},
version = {1.0.0},
year = {2025}
}
```
---
If you find this project helpful, please consider giving it a ⭐ star! Your support is greatly appreciated.
Made by the SUE-Sim Project Team