mmu.library — Hardware-Independent MMU Programming¶

mmu.library (Thomas Richter, v46.3) is the operating-system-level abstraction over the MC68K memory management unit, shipped as part of the NDK 3.2 MuManual/. It fills a gap that AmigaOS had since the beginning: "There's up to now no OS support for the MMU at all." Before mmu.library, every tool that touched the MMU — Enforcer, CyberGuard, GuardianAngle, SetCPU, Shapeshifter, VMM, GigaMem — programmed the hardware itself, and these tools conflict with each other. mmu.library provides a single, hardware-independent, OS-friendly API so they no longer have to.

What it does, and what it deliberately does not¶

mmu.library lets you read/write-protect memory regions, mark regions as "swapped out," and build per-task address-translation trees. Crucially, it does not implement virtual memory itself — that is the job of memory.library, which layers on top of mmu.library. Per the documentation: "There's no much reason why any application except the memory.library and probably some debugging tools should call this library directly."

The flagship consumer is MuForce, the mmu.library-native successor to Enforcer (see Amiga Debugging Tools). Because MuForce goes through mmu.library, it cooperates with virtual memory instead of fighting it.

The "context" — the central abstraction¶

The basic object is the context: the software abstraction of an MMU translation tree, holding the memory status for a set of tasks. At init, mmu.library builds a global context by snooping the existing MMU tree (or building one from available memory and expansion devices).

Tasks that do not explicitly enter their own context share the global context.
Programs can build private contexts and EnterMMUContext()/LeaveMMUContext().
Several tasks may share one context (e.g. multiple "threads" of one program).

Naming inversion to watch for: "a 'context' in the Amiga world is called a 'process' in Unix, and a 'task' or 'process' in the Amiga world is called a 'thread' usually." Don't let this trip you up when reading the autodocs.

Only debugging tools should mutate the global context directly — for example, an Enforcer-like tool marks unused memory and the first 4K as "invalid" to catch wild pointers.

The two per-context hooks¶

Each context carries two hooks the library keeps carefully distinct:

Hook	Fires when
Bus error hook	Access to an invalid address, or a write to a read-only region
Segmentation fault hook	Access to a page marked "swapped out" (i.e. paged to disk)

Default hooks just invoke the running task's exception handler → Guru Meditation. A debugging tool (MuForce) or the virtual-memory layer (memory.library) installs its own hooks to handle the fault productively.

API surface (autodoc categories)¶

The MuManual/Autodocs/mmu.doc TOC groups ~55 functions:

Contexts — CreateMMUContextA(), DeleteMMUContext(), EnterMMUContext(), LeaveMMUContext(), CurrentContext(), DefaultContext(), LockMMUContext() / AttemptLockMMUContext(), LockContextList(), context data get/set.
Mapping — NewMapping(), ReleaseMapping(), MapWindow() / MapWindowCached(), CopyMapping(), DupMapping(), RemapSize(), CopyContextRegion().
Properties — GetMappingProperties() / SetMappingProperties(), GetPageProperties() / SetPageProperties(), GetMapping(), GetPageSize(), GetPageUsedModified().
Physical location — PhysicalLocation(), PhysicalPageLocation(), indirect/line-vector helpers.
Hooks & exceptions — AddContextHook() / RemContextHook(), AddMessageHook() / RemMessageHook(), SetBusError(), ActivateException() / DeactivateException().
DMA — DMAInitiate() / DMATerminate() (DMA-safe MMU awareness).
Query — GetMMUType() (which CPU/MMU generation), GetPageSize().
Debugging UI — CreateContextWindow(), LayoutContextWindow(), RefreshContextWindow(), ReleaseContextWindow() (render the translation tree for inspection).

Representative signatures: context = CreateMMUContextA(tags); and pagesz = GetPageSize(context);.

Relationship to the rest of the OS¶

mmu.library is the foundation layer; sitting above it are:

memory.library — the virtual-memory project built on mmu.library (documented in the same MuManual/ tree as memory.doc).
MuForce / MuTools — the debugging tools that replace Enforcer and friends; see Amiga Debugging Tools.
CPU/FPU support libraries in the same manual tree: 68040.doc, 68060.doc, 680x0.doc, fpsp.doc (floating-point support package), exceptions.doc, disassembler.doc. The exec release notes note that exec itself does not identify the 68060, so mmu.library and the 68060.library are where 68060-specific behavior is coordinated.

Licensing note¶

mmu.library ships under the THOR-Software Licence (v2, 1998): freely redistributable for non-commercial use; commercial CD redistribution permitted under stated conditions. It is a third-party contribution included in the NDK by permission, not a Hyperion-owned component — unlike the core libraries.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search