# rach-kaplin/m.a.r.s. architecture

> Architecture diagram of the GitHub repository rach-kaplin/m.a.r.s., generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rach-kaplin/m.a.r.s.
- Repository: https://github.com/rach-kaplin/m.a.r.s.

## Overview

M.A.R.S. is a command-line microarchitecture research tool: users configure active hardware probes, run selected measurements, and receive a CPU-characteristics summary. The application registers enabled measurers, a probe service coordinates them against shared result data, and the summary printer presents the findings. Measurement modules probe distinct cache, translation, execution, and branch-prediction properties; platform services provide architecture-specific timing, operating-system controls, performance counters, and event discovery. Several measurement implementations and application call sites were not excerpted, so those links are marked unverified rather than inferred as confirmed calls.

Main entry points: [`include/core/measurer_registry.hpp`](https://github.com/rach-kaplin/m.a.r.s./blob/main/include/core/measurer_registry.hpp) (Measurer Registry), [`include/shared_types/cpu_info_data.hpp`](https://github.com/rach-kaplin/m.a.r.s./blob/main/include/shared_types/cpu_info_data.hpp) (CPU Measurement Results), [`src/app/application.cpp`](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/app/application.cpp) (Application Runner), [`src/measurement/exec_ports/exec_ports_measurer.cpp`](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/exec_ports/exec_ports_measurer.cpp) (Execution Ports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application"]
  node_cli["CLI Entry<br/>[main.cpp]"]
  node_config["Configuration<br/>[config_loader.cpp]"]
  node_application_runner["Application Runner<br/>[application.cpp]"]
  node_registry["Measurer Registry"]
  node_probe_service["Probe Service<br/>[probe_service.hpp]"]
  node_logger["Logging<br/>[logging.hpp]"]
end

subgraph group_measurements["Hardware Probes"]
  node_cache["Cache Sizing<br/>[cache_measurer.cpp]"]
  node_tlb["TLB Sizing<br/>[tlb_measurer.cpp]"]
  node_rob["ROB Sizing<br/>[rob_measurer.cpp]"]
  node_exec_ports["Execution Ports"]
  node_uops["Uop Cache"]
  node_btb["Branch Target Buffer"]
  node_bht["Branch History"]
  node_ras["Return Stack"]
  node_stlf["Store-Load Forwarding"]
  node_write_buffer["Write Buffer"]
end

subgraph group_platform["Platform Services"]
  node_architecture["CPU Architecture<br/>[arch_x86.cpp]"]
  node_os["OS Measurement Controls<br/>[os_linux.cpp]"]
  node_events["Event Discovery"]
  node_pmc["Performance Counters<br/>[pmc_linux.cpp]"]
end

subgraph group_results["Results"]
  node_cpu_data["CPU Measurement Results<br/>[cpu_info_data.hpp]"]
  node_summary["Summary Printer"]
end

node_user(("Researcher"))

node_user -->|"starts"| node_cli
node_cli -.->|"loads options"| node_config
node_cli -->|"starts"| node_application_runner
node_application_runner -->|"registers probes"| node_registry
node_application_runner -->|"runs probes"| node_probe_service
node_application_runner -.->|"prints summary"| node_summary
node_application_runner -.->|"configures logging"| node_logger
node_probe_service -->|"gets measurers"| node_registry
node_registry -.->|"registers"| node_cache
node_registry -.->|"registers"| node_tlb
node_registry -.->|"registers"| node_rob
node_registry -.->|"registers"| node_exec_ports
node_registry -.->|"registers"| node_uops
node_registry -.->|"registers"| node_btb
node_registry -.->|"registers"| node_bht
node_registry -.->|"registers"| node_ras
node_registry -.->|"registers"| node_stlf
node_registry -.->|"registers"| node_write_buffer
node_cache -.->|"writes results"| node_cpu_data
node_tlb -.->|"writes results"| node_cpu_data
node_rob -.->|"writes results"| node_cpu_data
node_exec_ports -.->|"writes results"| node_cpu_data
node_uops -.->|"writes results"| node_cpu_data
node_btb -.->|"writes results"| node_cpu_data
node_bht -.->|"writes results"| node_cpu_data
node_ras -.->|"writes results"| node_cpu_data
node_stlf -.->|"writes results"| node_cpu_data
node_write_buffer -.->|"writes results"| node_cpu_data
node_summary -->|"reads results"| node_cpu_data
node_cache -->|"uses timing"| node_architecture
node_tlb -->|"uses controls"| node_os
node_exec_ports -->|"discovers events"| node_events
node_exec_ports -->|"reads counters"| node_pmc
node_btb -->|"generates probes"| node_architecture
node_uops -->|"discovers events"| node_events
node_uops -->|"reads counters"| node_pmc
node_write_buffer -->|"discovers events"| node_events
node_write_buffer -->|"reads counters"| node_pmc

click node_cli "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/cli/main.cpp"
click node_config "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/app/config_loader.cpp"
click node_application_runner "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/app/application.cpp"
click node_registry "https://github.com/rach-kaplin/m.a.r.s./blob/main/include/core/measurer_registry.hpp"
click node_probe_service "https://github.com/rach-kaplin/m.a.r.s./blob/main/include/core/probe_service.hpp"
click node_logger "https://github.com/rach-kaplin/m.a.r.s./blob/main/include/infra/logging.hpp"
click node_cache "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/cache/cache_measurer.cpp"
click node_tlb "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/tlb/tlb_measurer.cpp"
click node_rob "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/rob/rob_measurer.cpp"
click node_exec_ports "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/exec_ports/exec_ports_measurer.cpp"
click node_uops "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/uops_cache/uops_cache_measurer.cpp"
click node_btb "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/branch_target_buffer/branch_target_buffer_measurer.cpp"
click node_bht "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/branch_history_table/branch_history_table_measurer.cpp"
click node_ras "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/return_address_stack/return_address_stack_measurer.cpp"
click node_stlf "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/store_to_load_forwarding/store_to_load_forwarding_measurer.cpp"
click node_write_buffer "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/write_buffer/write_buffer_measurer.cpp"
click node_architecture "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/platform/detail/arch_x86.cpp"
click node_os "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/platform/linux/os_linux.cpp"
click node_events "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/platform/linux/events_discovery_linux.cpp"
click node_pmc "https://github.com/rach-kaplin/m.a.r.s./blob/main/src/platform/linux/pmc_linux.cpp"
click node_cpu_data "https://github.com/rach-kaplin/m.a.r.s./blob/main/include/shared_types/cpu_info_data.hpp"
click node_summary "https://github.com/rach-kaplin/m.a.r.s./blob/main/include/core/summary_printer.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_application_runner,node_registry,node_probe_service,node_logger toneBlue
class node_cache,node_tlb,node_rob,node_exec_ports,node_uops,node_btb,node_bht,node_ras,node_stlf,node_write_buffer toneAmber
class node_architecture,node_os,node_events,node_pmc toneMint
class node_cpu_data,node_summary toneRose
class node_user toneIndigo
```

## Components

### Application

- [CLI Entry](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/cli/main.cpp): `src/cli/main.cpp`
- [Configuration](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/app/config_loader.cpp): `src/app/config_loader.cpp`
- [Application Runner](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/app/application.cpp): `src/app/application.cpp`
- [Measurer Registry](https://github.com/rach-kaplin/m.a.r.s./blob/main/include/core/measurer_registry.hpp): `include/core/measurer_registry.hpp`
- [Probe Service](https://github.com/rach-kaplin/m.a.r.s./blob/main/include/core/probe_service.hpp): `include/core/probe_service.hpp`
- [Logging](https://github.com/rach-kaplin/m.a.r.s./blob/main/include/infra/logging.hpp): `include/infra/logging.hpp`

### Hardware Probes

- [Cache Sizing](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/cache/cache_measurer.cpp): `src/measurement/cache/cache_measurer.cpp`
- [TLB Sizing](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/tlb/tlb_measurer.cpp): `src/measurement/tlb/tlb_measurer.cpp`
- [ROB Sizing](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/rob/rob_measurer.cpp): `src/measurement/rob/rob_measurer.cpp`
- [Execution Ports](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/exec_ports/exec_ports_measurer.cpp): `src/measurement/exec_ports/exec_ports_measurer.cpp`
- [Uop Cache](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/uops_cache/uops_cache_measurer.cpp): `src/measurement/uops_cache/uops_cache_measurer.cpp`
- [Branch Target Buffer](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/branch_target_buffer/branch_target_buffer_measurer.cpp): `src/measurement/branch_target_buffer/branch_target_buffer_measurer.cpp`
- [Branch History](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/branch_history_table/branch_history_table_measurer.cpp): `src/measurement/branch_history_table/branch_history_table_measurer.cpp`
- [Return Stack](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/return_address_stack/return_address_stack_measurer.cpp): `src/measurement/return_address_stack/return_address_stack_measurer.cpp`
- [Store-Load Forwarding](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/store_to_load_forwarding/store_to_load_forwarding_measurer.cpp): `src/measurement/store_to_load_forwarding/store_to_load_forwarding_measurer.cpp`
- [Write Buffer](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/measurement/write_buffer/write_buffer_measurer.cpp): `src/measurement/write_buffer/write_buffer_measurer.cpp`

### Platform Services

- [CPU Architecture](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/platform/detail/arch_x86.cpp): `src/platform/detail/arch_x86.cpp`
- [OS Measurement Controls](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/platform/linux/os_linux.cpp): `src/platform/linux/os_linux.cpp`
- [Event Discovery](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/platform/linux/events_discovery_linux.cpp): `src/platform/linux/events_discovery_linux.cpp`
- [Performance Counters](https://github.com/rach-kaplin/m.a.r.s./blob/main/src/platform/linux/pmc_linux.cpp): `src/platform/linux/pmc_linux.cpp`

### Results

- [CPU Measurement Results](https://github.com/rach-kaplin/m.a.r.s./blob/main/include/shared_types/cpu_info_data.hpp): `include/shared_types/cpu_info_data.hpp`
- [Summary Printer](https://github.com/rach-kaplin/m.a.r.s./blob/main/include/core/summary_printer.hpp): `include/core/summary_printer.hpp`

### Other components

- **Researcher**

## Connections

- Researcher → CLI Entry: starts
- CLI Entry → Configuration: loads options
- CLI Entry → Application Runner: starts (evidence: `src/cli/main.cpp`)
- Application Runner → Measurer Registry: registers probes (evidence: `src/app/application.cpp`)
- Application Runner → Probe Service: runs probes (evidence: `src/app/application.cpp`)
- Application Runner → Summary Printer: prints summary (evidence: `src/app/application.cpp`)
- Application Runner → Logging: configures logging (evidence: `src/app/application.cpp`)
- Probe Service → Measurer Registry: gets measurers (evidence: `include/core/probe_service.hpp`)
- Measurer Registry → Cache Sizing: registers
- Measurer Registry → TLB Sizing: registers
- Measurer Registry → ROB Sizing: registers
- Measurer Registry → Execution Ports: registers
- Measurer Registry → Uop Cache: registers
- Measurer Registry → Branch Target Buffer: registers
- Measurer Registry → Branch History: registers
- Measurer Registry → Return Stack: registers
- Measurer Registry → Store-Load Forwarding: registers
- Measurer Registry → Write Buffer: registers
- Cache Sizing → CPU Measurement Results: writes results
- TLB Sizing → CPU Measurement Results: writes results
- ROB Sizing → CPU Measurement Results: writes results
- Execution Ports → CPU Measurement Results: writes results
- Uop Cache → CPU Measurement Results: writes results
- Branch Target Buffer → CPU Measurement Results: writes results
- Branch History → CPU Measurement Results: writes results
- Return Stack → CPU Measurement Results: writes results
- Store-Load Forwarding → CPU Measurement Results: writes results
- Write Buffer → CPU Measurement Results: writes results
- Summary Printer → CPU Measurement Results: reads results (evidence: `include/core/summary_printer.hpp`)
- Cache Sizing → CPU Architecture: uses timing
- TLB Sizing → OS Measurement Controls: uses controls
- Execution Ports → Event Discovery: discovers events
- Execution Ports → Performance Counters: reads counters
- Branch Target Buffer → CPU Architecture: generates probes
- Uop Cache → Event Discovery: discovers events
- Uop Cache → Performance Counters: reads counters
- Write Buffer → Event Discovery: discovers events
- Write Buffer → Performance Counters: reads counters
