# jnavila/memtester architecture

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

- Interactive diagram: https://gitdiagram.com/jnavila/memtester
- Repository: https://github.com/jnavila/memtester

## Overview

##### Project type and purpose
- memtester is a standalone, command-line utility written in C that stress-tests a machine’s RAM.
- It is not a client/server or web app but a monolithic CLI tool that performs in-process memory tests and interacts directly with the OS.

##### File structure
- Top-level C source and headers:
- memtester.c       – program entry point, argument parsing, orchestration
- tests.c/.h        – implementations of individual memory tests (walking bits, random patterns, etc.)
- output.c/.h       – formatting and printing test results
- types.h, sizes.h  – platform abstractions (integer sizes, type definitions)
- memtester.h       – shared declarations (e.g., global options, API between main and tests)
- trycpp.c          – small C++ compilation test (platform/compiler probe)
- extra-libs.sh, conf-cc, conf-ld – build probe/config helpers
- Build and install:
- Makefile (with rules for compile, makelib, load, install)
- make-compile.sh, make-makelib.sh, make-load.sh – auxiliary wrappers
- BUGS, CHANGELOG, COPYING – documentation/legal

##### README for additional insights
- Single binary with optional “-p physaddr” and “-d device” flags that mmap()/mlock() physical memory.
- Core goals: portability across Unix-like systems, full 64-bit awareness, fast execution.
- No external services: everything runs in the process, but it relies on POSIX syscalls (mlock, mmap, strtoull, etc.).

##### Main components and their interactions
a. CLI Frontend (memtester.c)
- Parses arguments (memory size, run count, -p/-d options)
- Configures OS mode: standard heap allocation or mmap(physical)
- Initializes global state (do_mlock flag, page size, signal handlers)
- Hands off to the Test Orchestrator
b. Memory Manager
- Standard path: calloc()/malloc()
- Physical-memory path: open(device) → mmap() → optionally mlock()
- Exposes a pointer and byte-count to the orchestrator
c. Test Orchestrator (memtester.c → tests API)
- Iteratively invokes each test function in tests.c
- Passes the memory buffer pointer + size
- Collects pass/fail results
d. Test Modules (tests.c/.h)
- Each test implements a signature like `int test_xxx(uint8_t *buf, size_t size)`
- Tests include bit walking, random patterns, modulo patterns, fragment tests
e. Output/Reporting (output.c/.h)
- Receives test names and statuses, prints formatted output to stdout/stderr
- Handles verbosity, run counters, and error stops
f. OS Interface
- mlock(), munlock() if locking enabled
- open()/mmap()/munmap() on /dev/mem for physical address testing
- strtoull() for parsing memory sizes
- exit codes and signals for failures

##### Architectural patterns and design principles
- Modular decomposition: clear separation of CLI logic, memory allocation, test implementations, and output formatting.
- POSIX abstraction: uses platform-probe files (conf-cc, conf-ld) and code in types.h/sizes.h to adapt to different word sizes.
- Single-process, in-memory pipeline: no threads, no network.

##### Putting it all together
- Outside that, show interactions with kernel (syscalls) and /dev/mem.
- A sidebar for build-time components that generate the binary.

## Diagram (Mermaid)

```mermaid
graph TB
    %% memtester process
    subgraph "memtester Process"
        CLI["CLI Frontend\n(memtester.c, memtester.h)"]:::internal
        MM["Memory Manager\n(malloc()/mmap())"]:::internal
        ORG["Test Orchestrator\n(memtester.c, tests.h)"]:::internal
        subgraph "Test Modules"
            T1["test_xxx(uint8_t *buf, size_t size)\n(tests.c, tests.h)"]:::internal
        end
        OUT["Output/Reporting\n(output.c, output.h)"]:::internal
        PA["Platform Abstractions\n(types.h, sizes.h)"]:::internal
    end

    %% OS / Kernel Interface
    subgraph "OS / Kernel Interface"
        SYS["Syscalls\n(mlock, munlock, mmap, munmap, open, exit)"]:::os
        DEV["/dev/mem"]:::os
        PARSE["strtoull() Parsing"]:::os
    end

    %% Build & Configuration System
    subgraph "Build & Configuration"
        BM["Makefile"]:::build
        CC["conf-cc / conf-ld"]:::build
        EL["extra-libs.sh"]:::build
        MC["make-compile.sh"]:::build
        ML["make-makelib.sh"]:::build
        LD["make-load.sh"]:::build
        FS["find-systype.sh"]:::build
        TP["Build Probe\n(trycpp.c)"]:::build
    end

    %% Documentation & Legal
    subgraph "Documentation & Legal"
        RD["README"]:::doc
        BUG["BUGS"]:::doc
        CHG["CHANGELOG"]:::doc
        CPG["COPYING"]:::doc
        MAN["Manual Page\n(memtester.8)"]:::doc
    end

    %% Connections
    CLI -->|"alloc params"| MM
    MM -->|"buffer ptr+size"| ORG
    ORG -->|"invoke tests"| T1
    T1 -->|"test result"| OUT
    ORG -->|"syscall calls"| SYS
    SYS --> DEV
    CLI -->|"uses types/sizes"| PA
    ORG -->|"uses types/sizes"| PA
    OUT -->|"stdout/stderr"| SYS

    %% Click Events
    click CLI "https://github.com/jnavila/memtester/blob/master/memtester.c"
    click CLI "https://github.com/jnavila/memtester/blob/master/memtester.h"
    click MM "https://github.com/jnavila/memtester/blob/master/memtester.c"
    click ORG "https://github.com/jnavila/memtester/blob/master/memtester.c"
    click ORG "https://github.com/jnavila/memtester/blob/master/tests.h"
    click T1 "https://github.com/jnavila/memtester/blob/master/tests.c"
    click T1 "https://github.com/jnavila/memtester/blob/master/tests.h"
    click OUT "https://github.com/jnavila/memtester/blob/master/output.c"
    click OUT "https://github.com/jnavila/memtester/blob/master/output.h"
    click PA "https://github.com/jnavila/memtester/blob/master/types.h"
    click PA "https://github.com/jnavila/memtester/blob/master/sizes.h"
    click BM "https://github.com/jnavila/memtester/tree/master/Makefile"
    click CC "https://github.com/jnavila/memtester/tree/master/conf-cc"
    click CC "https://github.com/jnavila/memtester/tree/master/conf-ld"
    click EL "https://github.com/jnavila/memtester/blob/master/extra-libs.sh"
    click MC "https://github.com/jnavila/memtester/blob/master/make-compile.sh"
    click ML "https://github.com/jnavila/memtester/blob/master/make-makelib.sh"
    click LD "https://github.com/jnavila/memtester/blob/master/make-load.sh"
    click FS "https://github.com/jnavila/memtester/blob/master/find-systype.sh"
    click TP "https://github.com/jnavila/memtester/blob/master/trycpp.c"
    click RD "https://github.com/jnavila/memtester/tree/master/README"
    click BUG "https://github.com/jnavila/memtester/tree/master/BUGS"
    click CHG "https://github.com/jnavila/memtester/tree/master/CHANGELOG"
    click CPG "https://github.com/jnavila/memtester/tree/master/COPYING"
    click MAN "https://github.com/jnavila/memtester/blob/master/memtester.8"

    %% Styles
    classDef internal fill:#d4f8d4,stroke:#2e8b57,stroke-width:1px
    classDef os fill:#e0f7ff,stroke:#1e90ff,stroke-width:1px
    classDef build fill:#fff4e5,stroke:#ff8c00,stroke-width:1px
    classDef doc fill:#ffebe8,stroke:#d32f2f,stroke-width:1px
```
