# ints81/cuda_driver_hooking architecture

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

- Interactive diagram: https://gitdiagram.com/ints81/cuda_driver_hooking
- Repository: https://github.com/ints81/cuda_driver_hooking

## Overview

##### Project type and purpose
- This is an open-source tooling project whose sole purpose is to demonstrate and implement CUDA Driver API hooking via the LD_PRELOAD mechanism.
- It provides a small shared library (“hook.so”) that intercepts calls into the CUDA driver, plus sample executables (test.cu, conv_test.cu) and a PyTorch script (torch_op_test.py) to exercise that hook.

##### File structure
- Top level:
- hook.cpp     – source of the preloaded shared library
- test.cu      – minimal CUDA program to test basic driver API calls
- conv_test.cu – small convolution example that also links against cuDNN
- torch_op_test.py – Python script running a Torch operation to exercise more CUDA calls
- README.md    – build/run instructions
- .gitignore   – ignore rules
- No rigid MVC or microservice pattern—this is a single-component hooking tool with multiple test drivers.

##### Extract insights from the README
- Build steps:
1. nvcc compiles hook.cpp into a PIC shared object, linking CUDA Driver API and dl.
2. nvcc compiles test.cu and conv_test.cu into executables.
3. You run any CUDA-using binary under LD_PRELOAD=./hook.so so that hook.so is injected at load time.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Test Applications Layer
    subgraph "Test Applications" 
        direction TB
        test["test.cu"]:::userland
        conv["conv_test.cu"]:::userland
        subgraph "torch_op_test.py"
            direction TB
            Python["Python Interpreter"]:::userland
            PyTorch["PyTorch (CUDA Bindings)"]:::userland
            Python --> PyTorch
        end
    end

    %% Documentation
    README["README.md"]:::userland

    %% Dynamic Linking and Hook Layer
    ld["ld-linux.so (Dynamic Linker)"]:::systemlib
    hook["hook.so"]:::hook
    ds["dlsym(RTLD_NEXT)"]:::systemlib

    %% System Libraries and Hardware
    libcuda["libcuda.so"]:::systemlib
    GPU["GPU Hardware"]:::hardware

    %% Connections
    test -->|"cuInit, cuLaunchKernel"| ld
    conv -->|"cuInit, cuLaunchKernel (cuDNN)"| ld
    PyTorch -->|"cuInit, cuLaunchKernel"| ld

    README -.-> ld

    ld -->|"LD_PRELOAD loads hook.so"| hook
    hook -->|"pre-hook / post-hook"| libcuda
    hook -->|"dlsym(RTLD_NEXT)"| ds
    ds -->|"real driver symbol"| libcuda
    libcuda -->|"driver calls"| GPU

    %% Click Events
    click hook "https://github.com/ints81/cuda_driver_hooking/blob/main/hook.cpp"
    click test "https://github.com/ints81/cuda_driver_hooking/blob/main/test.cu"
    click conv "https://github.com/ints81/cuda_driver_hooking/blob/main/conv_test.cu"
    click PyTorch "https://github.com/ints81/cuda_driver_hooking/blob/main/torch_op_test.py"
    click README "https://github.com/ints81/cuda_driver_hooking/blob/main/README.md"

    %% Styles
    classDef userland fill:#AED6F1,stroke:#2E86C1,color:#154360
    classDef hook fill:#F5B041,stroke:#B9770E,color:#7E5109
    classDef systemlib fill:#A9DFBF,stroke:#27AE60,color:#1E8449
    classDef hardware fill:#D5DBDB,stroke:#7B7D7D,color:#2C3E50
```
