# ramisheikh/cbp2025 architecture

> Architecture diagram of the GitHub repository ramisheikh/cbp2025, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramisheikh/cbp2025
- Repository: https://github.com/ramisheikh/cbp2025

## Overview

##### Main Simulator Engine
- Central executable (built via Makefile) which is “cbp”. This component is responsible for running simulations, processing trace files, and printing detailed simulation outputs (e.g., branch mispredictions, IPC, cache behavior, etc.).
- This engine’s workflow starts with trace input (from sample_traces) and ends with output logs/statistics.

##### Branch Predictor Interface Module
- Interfaces defined in cbp.h along with the implementation provided in cond_branch_predictor_interface.cc. This module defines the lifecycle methods (e.g., beginCondDirPredictor, notify_instr_fetch, get_cond_dir_prediction, etc.) that guide how branch predictions are made as instructions move through the simulated CPU pipeline.
- That these interfaces are static and unchangeable even though contestants may modify the actual prediction logic.

##### Competitor-Supplied Predictor(s)
- Contestant-developed branch predictor files: my_cond_branch_predictor.h and my_cond_branch_predictor.cc.
- Pre-integrated benchmark predictor (cbp2016_tage_sc_l.h) which is offered as a starting point. Also, indicate that contestants may combine or replace this with their own predictor according to specific memory budget constraints.
- That this predictor module interacts directly with the branch predictor interface module.

##### Supporting Libraries and Utilities
- “lib” directory as a collection of helper libraries. Mention core library files like bp.cc/h, cache.cc/h, parameters.cc/h, etc. This layer includes:
- CPU pipeline simulation support (e.g., resource_schedule.cc/h, sim_common_structs.h)
- Additional simulation components (e.g., prefetcher, uarchsim) that might be used to simulate cache/memory behavior.
- Spdlog subdirectory (logging, formatting, sinks) as a utility for detailed logging across the simulator.
- Usage of gzstream for stream compressed trace file input.

##### Trace and Output Handling
- An output component where the simulator writes logs and statistical data, and note that a Python script (scripts/trace_exec_training_list.py) parses these logs to generate CSV summaries.
- That trace files and results flow in and out of the simulator and testing harness.

##### Interactions and Data Flow
- From Trace Input to the Main Simulator Engine.
- Inside the simulator, show internal calls from the engine to the Branch Predictor Interface as instructions progress through pipeline stages.
- From the Branch Predictor interface to the Contestant-supplied Predictor module.
- That statistical metrics (misprediction counts, IPC, cache stats, etc.) are gathered by the simulation engine and then output to both logs and further processed by the Python script.

##### Architectural Patterns and Principles
- That the design is modular, with clear separation between the simulation engine and the prediction components.
- The simulator uses a plug-in pattern where the branch predictor logic is abstracted behind fixed interfaces (allowing contestants to build and modify predictors without affecting the core simulation flow).
- The usage of a rich library (with spdlog and gzstream) indicates a layered design and integration of third-party components for logging and I/O.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Trace and Output Handling
    subgraph "Trace and Output Handling"
        T("Trace Input (sample_traces)"):::io
        T_FP("FP Traces"):::io
        T_INT("INT Traces"):::io
        OP("Output Processing (Python Log Parser)"):::io
    end

    %% Simulation Core
    subgraph "Simulation Core"
        SM1("Executable (Makefile)"):::simCore
        SM2("Simulator Engine (lib/cbp.cc)"):::simCore
    end

    %% Branch Predictor Interface Module
    subgraph "Branch Predictor Interface"
        BPI1("Interface Definition (cbp.h)"):::interface
        BPI2("Interface Implementation (cond_branch_predictor_interface.cc)"):::interface
    end

    %% Competitor-Supplied Predictor(s)
    subgraph "Competitor Predictor"
        CP1("Predictor Header (my_cond_branch_predictor.h)"):::plugin
        CP2("Predictor Source (my_cond_branch_predictor.cc)"):::plugin
        CP3("Benchmark Predictor (cbp2016_tage_sc_l.h)"):::plugin
    end

    %% Supporting Libraries and Utilities
    subgraph "Supporting Libraries and Utilities"
        L1("Supporting Libs (lib)"):::libNode
    end

    %% Relationships and Data Flow
    T --> T_FP
    T --> T_INT
    T -->|"InputTrace"| SM2
    SM1 --> SM2
    SM2 -->|"init_predictor"| BPI1
    BPI1 -->|"delegate_predict"| CP1
    BPI1 --> BPI2
    CP1 --> CP2
    CP2 --> CP3
    SM2 -->|"uses_lib"| L1
    SM2 -->|"log_output"| OP

    %% Click Events
    click T "https://github.com/ramisheikh/cbp2025/tree/main/sample_traces"
    click T_FP "https://github.com/ramisheikh/cbp2025/tree/main/sample_traces/fp"
    click T_INT "https://github.com/ramisheikh/cbp2025/tree/main/sample_traces/int"
    click OP "https://github.com/ramisheikh/cbp2025/blob/main/scripts/trace_exec_training_list.py"
    click SM1 "https://github.com/ramisheikh/cbp2025/tree/main/Makefile"
    click SM2 "https://github.com/ramisheikh/cbp2025/blob/main/lib/cbp.cc"
    click BPI1 "https://github.com/ramisheikh/cbp2025/blob/main/cbp.h"
    click BPI2 "https://github.com/ramisheikh/cbp2025/blob/main/cond_branch_predictor_interface.cc"
    click CP1 "https://github.com/ramisheikh/cbp2025/blob/main/my_cond_branch_predictor.h"
    click CP2 "https://github.com/ramisheikh/cbp2025/blob/main/my_cond_branch_predictor.cc"
    click CP3 "https://github.com/ramisheikh/cbp2025/blob/main/cbp2016_tage_sc_l.h"
    click L1 "https://github.com/ramisheikh/cbp2025/tree/main/lib"

    %% Styles
    classDef simCore fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef interface fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef plugin fill:#f94144,stroke:#333,stroke-width:2px;
    classDef libNode fill:#577590,stroke:#333,stroke-width:2px;
    classDef io fill:#f3722c,stroke:#333,stroke-width:2px;
```
