IOMMU / GUIDED STORY

Testing an address-translation walk

Page tables, permissions and boundaries in a four-level teaching walk.

This independent example explores how to test a translation walk, built from public specifications, without reproducing a hardware implementation.

What claims does this page make? 1 point

Teaching model: the four-level, 512-entry, 4 KiB walk and its present and write fields are this site's own simplification, not any x86 IOMMU or Arm SMMU format.

The requirement

A translation should preserve the page offset, reject an unmapped page, and enforce the requested access permission throughout the walk.

The model

The example uses four levels of 512 entries and 4 KiB pages. Each entry is a C++ structure with abstract presence and write-permission fields. Input addresses are unsigned 48-bit values. This is a teaching model, not the encoding or complete behaviour of any x86 IOMMU or Arm SMMU.

FOLLOW ONE ADDRESS

Four indices. One page offset.

In this model, 0x1234 selects entry zero at the first three levels, then entry one in the leaf table.

Level 4 bits 47–39: 0
Level 3 bits 38–30: 0
Level 2 bits 29–21: 0
Level 1 bits 20–12: 1
Offset bits 11–0: 0x234

Mapped frame 0x9000Offset 0x234Output 0x9234

The offset is preserved. The table entries determine the frame and whether this model permits the access. These labels describe the synthetic walk, not an architecture-specific descriptor format.

What the tests check

Translate a mapped address and check the physical frame plus offset.
Probe the last byte of a page and the first byte of the next, unmapped page.
Remove write permission at an intermediate level; reads should still pass and writes should fail.
Reject an out-of-range input or a misaligned target.

Try a change

Change the intermediate entry’s write flag back to true. The negative write-permission test should report FAIL: the injected restriction has been removed, so the original expectation no longer holds.

C++ experiment

Default: C++23 · choose GCC or Clang below

Edit the source, then run the tests. Compilation provided by Compiler Explorer. Clicking Run sends the code to that external service. Use only public, non-confidential code.

Editable source

// Independent educational model. Not an x86 IOMMU or Arm SMMU register format.
// Four levels, 9-bit indices, 4 KiB pages; unsigned 48-bit input addresses.
#include <array>
#include <cstdint>
#include <iostream>
#include <map>
#include <optional>

struct Entry {
    std::uint64_t target = 0;
    bool present = false;
    bool write = false;
};

using Table = std::array<Entry, 512>;
using Tables = std::map<std::uint64_t, Table>;

std::optional<std::uint64_t> translate(const Tables& tables, std::uint64_t root,
                                       std::uint64_t address, bool write)
{
    if (address >> 48) {
        return {}; // Model limit, not a CPU canonical-address check.
    }

// Walk from the root table down to a 4 KiB frame.
    for (int shift : {39, 30, 21, 12}) {
        if (root & 0xfff) {
            return {};
        }
        auto table = tables.find(root);
        if (table == tables.end()) {
            return {};
        }

const auto index = (address >> shift) & 0x1ff;
        const auto& entry = table->second[index];

// Permissions are checked at every level in this model.
        if (!entry.present || (write && !entry.write) || (entry.target & 0xfff)) {
            return {};
        }
        if (shift == 12) {
            return entry.target | (address & 0xfff);
        }
        root = entry.target;
    }
    return {};
}

int main()
{
    // Arrange: three table links and one mapped leaf.
    Tables tables;
    tables[0x1000][0] = {0x2000, true, true};
    tables[0x2000][0] = {0x3000, true, true};
    tables[0x3000][0] = {0x4000, true, true};
    tables[0x4000][1] = {0x9000, true, true};

// Report every expectation; return nonzero on any failure.
    int failures = 0;
    auto check = [&](bool ok, const char* name) {
        std::cout << (ok ? "PASS " : "FAIL ") << name << '\n';
        failures += !ok;
    };
    auto walk = [&](std::uint64_t a, bool w = false) {
        return translate(tables, 0x1000, a, w);
    };

// Positive path and page-boundary checks.
    check(walk(0x1234) == std::optional<std::uint64_t>{0x9234}, "page offset preserved");
    check(walk(0x1fff) == std::optional<std::uint64_t>{0x9fff}, "last byte in page");
    check(!walk(0x2000), "next page is unmapped");

// Negative path: restrict writes at an intermediate level.
    tables[0x2000][0].write = false;
    check(walk(0x1234).has_value(), "read remains permitted");
    check(!walk(0x1234, true), "write denied by intermediate table");
    check(!walk(1ULL << 48), "out-of-model address rejected");
    tables[0x4000][1].target = 0x9001;
    check(!walk(0x1234), "misaligned frame rejected");
    return failures ? 1 : 0;
}

Download .cpp

Ready. No code has been sent.

Compiler & test output

Run the example to see actual output here.

If the external service is unavailable, copy the source and open Compiler Explorer, or compile locally with g++ -std=c++23 example.cpp -o example and run ./example.

What this does not establish

A passing software model does not validate real translation hardware. This example omits device contexts, architecture-specific descriptors, multiple translation stages, large pages, translation caches and invalidation, and fault-reporting mechanisms. CPU virtual-address translation and device DMA translation are distinct paths.

Public references

Linux DMA mapping guide: CPU and DMA addresses

Personal educational material; not an employer publication or endorsement.