Master

Debugging a module

A module has no debugger in the place it runs. The way in is printing from inside, and printing from inside is a decision about what the module is allowed to say.

What you will see

One line. A map is a build flag, so the build is stamped with it.

About 1 min of reading

Try It

Resolve an offset

1

Write the trap offset

printf 'trap_offset 48212\n' > /tmp/t.txt; cat /tmp/t.txt

Before you run it, say out loud what it will print. Then open the answer.

What it prints
One line. An offset alone is a number nobody can fix.
2

Resolve with the map

printf '48212 walk_tree\n' > /tmp/map.txt; grep 48212 /tmp/map.txt

Before you run it, say out loud what it will print. Then open the answer.

What it prints
48212 walk_tree. The name is the thing that can be opened in an editor.
3

Stamp the build used

printf 'build=debug map=yes date=2026-10-10\n' > /tmp/b.txt; cat /tmp/b.txt

Before you run it, say out loud what it will print. Then open the answer.

What it prints
One line. A map is a build flag, so the build is stamped with it.

Data Flow

A trap to a line
1 The module traps at an offset
↓
2 The symbol map is loaded
↓
3 The offset is resolved to a name
↓
4 The name is written with the run stamp
Why this works
Why the map is kept

The map is the only link between an offset and a name. A shipped module without a map is a module that cannot be read.

The cost of the channel

The buffer is copied per crossing. Debug output is a cost, and a cost that ships is a cost that is measured.

Examples

The print crosses the boundary

The module writes to a buffer and the host reads it. The buffer is the channel, and the channel has a size.

Why the trap is the clue

A trap gives an offset. The offset plus the symbol map is a line, and the map is a build flag.

The release build lies

Optimisation removes the values that were printed. Debugging is done on a build that is not shipped.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← The host is a component
Previous Lesson
The host is a component
Next Lesson
Shipping a bounded system
Shipping a bounded system →