← 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 and the Mantissa Bridge extension (one-line install, see Setup).
• 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 the Mantissa Debugger find your active VS Code debug session. Installs in one command:

  code --install-extension mantissa.mantissa-bridge

Or in VS Code's Extensions panel (Ctrl+Shift+X), search for Mantissa Bridge and click Install. There's 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. The earlier gdb-only bridge is being phased out.

1. Open the project

Pick your IDE. The button launches it on the bundled lab project automatically (when you're inside the Mantissa app); on the public web it points you at the download.

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.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 name on the right. The lab project's variable names match between the two builds — see the README.md for the suggested set (tap_state[0..3], accumulator, output).
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.

Download lab project zip · ← All tutorials