← All tutorials

Lab 1 — Debug a float vs. fixed-point port

A small DSP project ships in two builds — a float reference and a deliberately-broken fixed-point port. Open both in your IDE, attach with the Mantissa Debugger mode, bind float / fixed variable pairs, and find the variable that's quantizing badly. 20–30 minutes.

What you'll need

• Mantissa (you have it — that's how you got here).
• VS Code with the C/C++ extension. Optionally the Mantissa Bridge extension (one-line install) — gets you live float/fixed variable binding in Mantissa's Debugger panel. Without it the lab still works.
• A working g++ on your PATH (or clang++ on macOS). The lab uses GCC by default on every OS so it works in restricted Windows environments where corporate Group Policy blocks Microsoft's vcvars64.bat.
• The lab project — bundled with the app on the embedded view, or downloadable from the public web (see button below).

Setup

One-time install for each tool. If you already have VS Code + C/C++ extension + a C++ compiler in your PATH, skip ahead to Open the project.

1. VS Code

Download the installer for your OS: code.visualstudio.com/Download. Default install is enough; tick "Add to PATH" so the code CLI is available (the Mantissa embed launches the IDE through that shim).

2. C/C++ extension

In VS Code: open the Extensions panel (Ctrl+Shift+X), search for C/C++, install the one published by Microsoft. Or grab it from the marketplace. No further configuration needed.

3. C++ compiler (one of)

Verify by opening a fresh terminal and running:

  g++ --version

If the version prints, you're done. If not, the compiler isn't on your PATH — re-check the install steps for your OS.

4. Mantissa Bridge (VS Code extension)

A tiny extension that lets Mantissa's Debugger mode find your active VS Code debug session — so when you bind float / fixed pairs, they update live as you step. Without it the lab still works (you can debug in VS Code on its own), but you lose the live-binding feature in Mantissa's Debugger panel.

Or — same thing in one terminal command:

  code --install-extension mantissa.mantissa-bridge

Or — Extensions panel in VS Code (Ctrl+Shift+X) → search Mantissa Bridge → Install. Nothing to configure — once installed, every debug session you start is automatically discoverable from Mantissa.

Why a separate extension? It works for every debugger VS Code supports — gdb, lldb, MSVC's cppvsdbg, debugpy — with a single install, instead of needing per-debugger plugins. Source lives at mantissa/integrations/vscode-bridge.

1. Open the project

Point VS Code at the folder you extracted the zip into. Inside the Mantissa app the lab is bundled, so the IDE button just works without a path.

"window.openFoldersInNewWindow": "on"

2. Run both builds

1. Build and run the float target. It writes out_float.wav to the project directory.
2. Build and run the fixed target. It writes out_fixed.wav alongside.
3. You'll hear them sound subtly different — that's the bug. Now let's find it.

3. Attach the Mantissa Debugger

Switch to Debugger mode

1. Set a breakpoint at the entry of FirFixed::process in fixed/fir_fx.h (or wherever you suspect the bug lives).
2. Click the button above to jump straight to the Mantissa Debugger mode. (On the public web this just navigates to the Debugger info page — the actual mode lives in the desktop app.) Once there, click the Search icon. The Bridge extension exposes your live debug session, so it shows up in the picker right away — no extra setup, no ~/.gdbinit editing, no PID-file dance.
3. Pick your session from the dropdown. The locals tree populates from whatever frame you're stopped on.
4. Add watch pairs for the suspect variables: float reference name on the left, fixed-point twin (with the _fx suffix) on the right — e.g. state[i] ↔ state_fx_[i], acc ↔ acc_fx, y ↔ y_fx. See the README.md's Variables to bind table for the full set and suggested Q-format per row.
5. Click Auto-Q on each pair to recover the Q-format from the live values; the suggested Q is the one the broken build thinks it's using. Compare against the README's "expected Q per variable" table.

4. Find the regression

Step through one block. Watch the per-pair MLD column for the biggest jump — that's the variable where the fixed build diverged from the float reference. Common culprits:

• Wrong Q-factor on the accumulator (overflow before saturation).
• Unsigned shift instead of signed for negative samples.
• Half-towards-zero rounding instead of half-away-from-zero.

The README has the answer at the bottom — but try to find it yourself first.

Next: analyse the output

Once you've located the bad variable, the output of the two builds (out_float.wav vs. out_fixed.wav) is what the listener actually hears. Continue with Lab 2 — analyse output with Wave Compare to see what the regression sounds like in the spectrum.

Re-download lab zip · ← All tutorials