DigInside
Tagline: A visualizer for Intro to Machine organization (CS 354) and Operating Systems (CS 537): see which cores your program's threads run on, and what's in the cache on every memory access.
Inspiration
I'm a peer mentor for CS 354 (Machine Organization and Programming) at UW–Madison. Week after week, students hit the same wall: threads, scheduling and caches are all things they can't see. They can recite "a set-associative cache has S sets of E lines," but when their matrix code is slow they can't say why. The usual tools either hide all of this or bury it in numbers. I wanted something where you drop in a small C program, press Run, and watch it: threads landing on cores, and every load and store filling a cache, explained in plain words.
What it does
DigInside is a web app built around one canvas. It adapts to the machine it runs on: it asks the OS how many CPUs your program can use and draws one node per core (16 on my laptop), and it reads your CPU's real cache sizes so you can simulate your own L1.
Watch threads on real cores
- Drag any C, C++, Python or shell file from the sidebar onto the canvas and press Run. It compiles if needed, and you can edit the compile command (e.g.
-O0vs-O3, or ThreadSanitizer). - Every CPU core is a node. Your program's threads appear on the core they're running on, move live when the scheduler migrates them, and show how busy they are.
- Draw an edge from a program to a core to pin it there (real CPU affinity). Change the edges while it runs and the threads move.
- Live stats: user vs kernel time, context switches, a syscall stream (via
strace), CPU time per core, and parallel speedup. Every run is saved in a history table, so you can compare 1 vs 2 vs 4 vs 8 threads side by side.
Watch the cache
- Add a Cache module from the menu, choose its size (sets, lines per set, block size, or your CPU's real L1), and connect a program to it. Press Run and the cache fills with that program's memory accesses.
- Step through accesses one at a time. Each step is explained in one sentence, e.g. "line 25
local[i] = 2*iwriteslocal[1]→ its block belongs in set 3 → conflict miss: other blocks that map to set 3 pushed it out." - Three side-by-side views connect the cache's sets, the lines in a set (valid bit, dirty bit, tag, and which variables the block holds) and your program's memory (globals, heap, stack), with wires showing which line holds which block.
- Every miss is classified as cold, conflict or capacity.
How I built it
- Backend: Python + FastAPI. It launches programs, samples Linux's per-thread
/procfiles every 50 ms (which core, how long on-CPU, context switches), parsesstraceoutput, and streams it all over a WebSocket. - Cache simulator: a set-associative cache with LRU replacement and write-back, written from scratch. It classifies each miss by comparing against a fully associative cache of the same size.
- Memory traces, two ways:
tarray.hpp, a C++ array type that logs every element read and write, for clean, named, repeatable traces.- Valgrind, which records the real loads and stores of the compiled machine code, for any unmodified C/C++ program. I keep only the accesses made by your own code, and name them using the program's debug info, so the cache says
i,local[3],g[4]instead of hex addresses.
- Frontend: React + TypeScript + Vite, with React Flow for the canvas.
Challenges
- Noise. Valgrind sees about 52,000 memory accesses for a 20-line program; almost all of them are program startup and the C library. Keeping only the 418 that
mainmakes, and naming local variables (which meant working out where each function's stack frame sits from the trace itself), was the hardest part. - The observer effect.
straceslows syscall-heavy programs dramatically (64-byte writes went from 437 MB/s to 1 MB/s), so tracing can be toggled off per program.
Accomplishments I'm proud of
- The simulator matches the reference. It reproduces the CS:APP Cache Lab handout example access by access.
- Its predictions hold on real hardware. For matrix multiply, it ranks the loop orders ikj < ijk < jki by miss rate (24.7% / 53.3% / 67.0%), and the real CPU agrees: 0.31 s / 2.5 s / 6.2 s at N = 1024.
- The parallel speedup is visible. Going from 1 to 8 threads takes matmul from 1.70 s to 0.35 s (4.8×). Total CPU time rises (1.6 s → 2.1 s) while CPU time per thread drops from 1.6 s to 0.26 s.
What I learned
- How Linux exposes scheduling (per-thread
/procfiles andschedstat), and how much tools likestracedisturb what they measure. - How Valgrind instruments machine code, and how debug info maps machine code back to variables and source lines.
- Explaining a concept in one plain sentence is harder, and more useful, than drawing it.
What's next
- DigInside is built from modules you wire together on one canvas, so it can grow to cover much more of the machine: TLBs and page tables to show how a virtual address becomes a physical one, multi-level caches (L1 → L2 → L3) chained together with edges, and caches shared between cores to show how coherence keeps threads' views of memory consistent.
- A GPU module: NVIDIA's streaming multiprocessors (SMs) drawn as nodes, so you can launch a CUDA kernel and watch thread blocks get scheduled onto SMs, warps of 32 threads run in lockstep on CUDA cores, and threads that branch apart (divergence) or read scattered memory (uncoalesced access) slow everything down.
- Test on native Linux (lab machines, and a Rubik Pi with its mix of big and little cores).
- Show the actual values stored in cache lines, not just which variables they hold.
Built with
Python, FastAPI, Uvicorn, WebSockets, C, C++, g++/gcc, Valgrind, strace, pyelftools (DWARF), React, TypeScript, Vite, React Flow, Linux /proc
Built With
- c
- c++
- fastapi
- linux
- pyelftools
- python
- react
- reactflow
- strace
- typescript
- uvicorn
- valgrind
- vite
- websockets