# anubhavbhatla/maya-cache architecture

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

- Interactive diagram: https://gitdiagram.com/anubhavbhatla/maya-cache
- Repository: https://github.com/anubhavbhatla/maya-cache

## Overview

##### Major Components
- Performance Evaluation Module (performance-analysis):
– Contains simulation subprojects (notably “maya” and “mirage”) with source code, build scripts (compile.sh, Makefile), and specialized directories for cache, branch predictors, prefetchers, and replacement policies.
– Includes tools for generating simulation binaries, running long-time simulations (run.sh, run_1core_gap.sh, etc.), and plotting simulation results (plot.sh).
– Uses external data dependencies like GAP traces and SPEC CPU benchmarks, whose location is referenced in the README.

- Security Evaluation Module (security-analysis):
– Contains its own build scripts (Makefile) and programs (C++ code in src such as security_maya.cpp) used to compile and run security simulations.
– Has dedicated scripts (run.sh, plot.py) for executing the simulations and generating security-related plots.

- Shared Tools/Global Artifacts:
– Top-level scripts like requirements.txt (for Python dependencies), trace scripts, and overall run scripts.
– Configuration and dependency management (instructions in the README detail how to download traces and run the appropriate scripts).

##### Relationships and Data Flow
- The simulation flow begins with the acquisition of necessary input traces (GAP and SPEC benchmarks). These inputs feed into both performance and security simulation engines.
- In the performance module, the simulation binaries (in “maya” and “mirage”) are generated by compiling the source code. Simulation runs are orchestrated using various run scripts, and the results (text files, CSV files, logs) are collected in “original_results” subdirectories.
- The output from the simulation binaries then is processed by plotting scripts (plot.sh) to generate the final graphs (such as fig1.pdf and fig10.pdf) as indicated in the README.
- In parallel, the security module follows a similar build-run-plot cycle, using Makefile builds, simulation execution (run.sh), and Python plotting (plot.py) to produce its results (fig7.pdf, fig8.pdf).

##### Architectural Patterns and Technologies
- The project follows a modular structure by separating performance analysis from security evaluation. In the performance module the simulation subprojects (“maya” and “mirage”) are further divided into components according to their simulation functionality (branch predictors, prefetchers, etc.).
- Design principles include separation of concerns (evaluation of performance versus security), script-driven automation (using shell/Python scripts to drive the workflow), and dependency on external data artifacts.
- Technologies include C/C++ for simulation engine implementations, Make and shell scripting for builds/automation, and Python (via requirements.txt and plot.py) for plotting and analysis.

##### Final Touches
- Provide annotations or notes indicating that certain modules (e.g., the “maya” and “mirage” components) are part of a comprehensive simulation framework geared toward evaluating high-performance cache architectures.
- Mention that the simulation process is long-running (the README states 5-6 days) and that the interdependencies, such as the need to download traces manually, are critical to the system design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Tools & External Data
    GlobalTools["Global Tools & Artifacts"]:::global
    ExternalData["External Trace Data (GAP, SPEC)"]:::external

    %% Performance Evaluation Module Subgraph
    subgraph "Performance Evaluation Module"
        PerfModule["Performance Evaluation Module"]:::simulation
        PerfBuildRun["Build & Run Scripts (Performance)"]:::build

        %% Maya Simulation Subgraph
        subgraph "Maya Simulation"
            MayaSim["Maya Simulation"]:::simulation
            MayaBranch["Branch Predictor (Maya)"]:::simulation
            MayaPrefetch["Prefetcher (Maya)"]:::simulation
            MayaReplacement["Replacement Policy (Maya)"]:::simulation
        end

        %% Mirage Simulation Subgraph
        subgraph "Mirage Simulation"
            MirageSim["Mirage Simulation"]:::simulation
            MirageBranch["Branch Predictor (Mirage)"]:::simulation
            MiragePrefetch["Prefetcher (Mirage)"]:::simulation
            MirageReplacement["Replacement Policy (Mirage)"]:::simulation
        end

        SimulationResults["Simulation Results"]:::results
        PerfPlot["Plotting (plot.sh)"]:::plotting
    end

    %% Security Evaluation Module Subgraph
    subgraph "Security Evaluation Module"
        SecModule["Security Evaluation Module"]:::security
        SecBuild["Security Source & Build"]:::security
        SecRun["Run Script (security-analysis/run.sh)"]:::security
        SecPlot["Plotting (plot.py)"]:::plotting
    end

    %% Data Flow Connections
    GlobalTools --> PerfModule
    GlobalTools --> SecModule

    ExternalData --> MayaSim
    ExternalData --> MirageSim

    PerfModule --> PerfBuildRun
    PerfBuildRun --> MayaSim
    PerfBuildRun --> MirageSim

    MayaSim --> MayaBranch
    MayaSim --> MayaPrefetch
    MayaSim --> MayaReplacement

    MirageSim --> MirageBranch
    MirageSim --> MiragePrefetch
    MirageSim --> MirageReplacement

    MayaSim & MirageSim --> SimulationResults
    SimulationResults --> PerfPlot

    SecModule --> SecBuild
    SecBuild --> SecRun
    SecRun --> SecPlot

    %% Click Events for Performance Module
    click PerfModule "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis"
    click MayaSim "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis/maya"
    click MirageSim "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis/mirage"
    click MayaBranch "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis/maya/branch"
    click MirageBranch "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis/mirage/branch"
    click MayaPrefetch "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis/maya/prefetcher"
    click MiragePrefetch "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis/mirage/prefetcher"
    click MayaReplacement "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis/maya/replacement"
    click MirageReplacement "https://github.com/anubhavbhatla/maya-cache/tree/main/performance-analysis/mirage/replacement"
    click PerfBuildRun "https://github.com/anubhavbhatla/maya-cache/blob/main/performance-analysis/compile.sh"
    click PerfPlot "https://github.com/anubhavbhatla/maya-cache/blob/main/performance-analysis/plot.sh"

    %% Click Events for Security Module
    click SecModule "https://github.com/anubhavbhatla/maya-cache/tree/main/security-analysis"
    click SecBuild "https://github.com/anubhavbhatla/maya-cache/tree/main/security-analysis/src"
    click SecRun "https://github.com/anubhavbhatla/maya-cache/blob/main/security-analysis/run.sh"
    click SecPlot "https://github.com/anubhavbhatla/maya-cache/blob/main/security-analysis/plot.py"

    %% Click Event for Global Tools
    click GlobalTools "https://github.com/anubhavbhatla/maya-cache/blob/main/requirements.txt"

    %% Styles
    classDef global fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef external fill:#FFCCBC,stroke:#333,stroke-width:2px;
    classDef simulation fill:#B39DDB,stroke:#333,stroke-width:2px;
    classDef build fill:#80DEEA,stroke:#333,stroke-width:2px;
    classDef plotting fill:#A5D6A7,stroke:#333,stroke-width:2px;
    classDef security fill:#FFAB91,stroke:#333,stroke-width:2px;
    classDef results fill:#C5E1A5,stroke:#333,stroke-width:2px;
```
