NfClr.Profiling 1.0.0-beta.1

NfClr

A memory and performance profiler for .NET nanoFramework — dotMemory / dotTrace for microcontrollers. It introspects a running nanoCLR (on the cycle-accurate emulator, no physical board) and answers the two questions every embedded developer asks: what's using my RAM, and where is my time going?

$ nfprof memory --firmware ./fw --deployment app.bin --until SetupDone

## Managed heap     used 14 400 B · free 217 056 B · total 231 456 B (123 objects)
| type                  | objects | bytes |
| PioStateMachineConfig |    3    |  756  |
| PioInstructionRef     |   29    |  696  |
| PioProgram            |    3    |  540  |
| "WS2812 ready"        |    1    |   28  |
## GC   3 collections

Real managed types — not "object: 40" — strings with their values, GC counters. And it exports the full heap as a Chrome DevTools .heapsnapshot and traces as a speedscope flame graph, so the rich, interactive UI comes from mature open tools — nothing to build, nothing to license.

What it gives you

Quick start

dotnet tool install -g NfClr.Tool   # provides `nfprof`

# What types use memory (Markdown for CI/PR, or --format json)
nfprof memory  --firmware ./fw --deployment app.bin --until SetupDone

# The full object graph → drop heap.heapsnapshot into Chrome DevTools › Memory › Load
nfprof memory  --firmware ./fw --deployment app.bin --until SetupDone \
               --format heapsnapshot --out heap.heapsnapshot

# Where time goes → open trace.speedscope.json at https://speedscope.app
nfprof calls   --firmware ./fw --deployment app.bin --until SetupDone \
               --instructions 5000000 --format speedscope --out trace.speedscope.json

# What an operation allocated (snapshot A → B)
nfprof memory  --firmware ./fw --deployment app.bin --diff --from SetupDone --until FrameRendered

--firmware is a directory with nanoBooter*.bin, nanoCLR*.bin and a firmware.manifest.json (symbol addresses, derived from the build's ELF). --until <symbol> runs into your code first.

Architecture

The nanoCLR's in-RAM layout is identical across the chips it runs on, so that knowledge lives once. Everything is chip-agnostic except a thin per-chip adapter — the same core serves every board and the tool. Profiles export to open formats, so the heavy UI is delegated to Chrome DevTools and speedscope.

NfClr.Core        the nanoCLR knowledge: heap walk, reference graph, call stacks,
   (IClrMemory / IClrHost)    type resolution — over a read/run abstraction. No chip.
        ▲
   per-chip test kit          the only chip-specific seam: an IClrMemory/IClrHost adapter
   (RP2040 today; STM32/ESP32) + the flash layout. STM32/ESP32 = just write their adapter.
        ▲
NfClr.Profiling   ProfileReport (Markdown/JSON), Speedscope, V8 .heapsnapshot.
        ▲
   nfprof (dotnet tool)        composition root: wires a concrete chip into the profiler.

Status

Mature for the common questions: real types, allocation diffs, GC, self-time profiling, and a navigable heap graph in DevTools. Known edges: sampling is per-emulated-instruction (deterministic and reproducible, rather than wall-clock); the graph roots from objects with no in-heap referrers (a close proxy for the GC root set); array elements are followed, value-type field internals are not.

License

Business Source License 1.1 (converts to MIT on the Change Date). See LICENSE-BUSL.txt.