NationalSecurityAgency/ghidra · error · IllegalArgumentException

Memory-mapped register {register} does not map to space {spa

Error message

Memory-mapped register {register} does not map to space {space}

What it means

Thrown by getConventionalRegisterRange for a memory-mapped register (one whose address space is NOT a register space) when the host-mapped result address space does not equal the caller-supplied 'space'. This is the memory-mapped-register counterpart to error 440: the register is expected to land in a specific memory space, but its guest-to-host translation placed it elsewhere. It protects callers from silently reading/writing the wrong memory region via a misaligned register mapping.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/guest/InternalTracePlatform.java:78

		AddressRange result = mapGuestToHost(TraceRegisterUtils.rangeForRegister(register));
		if (result == null) {
			throw new IllegalArgumentException("Register " + register + " is not mapped");
		}
		if (space == null) {
			return result;
		}
		if (register.getAddressSpace().isRegisterSpace()) {
			if (result.getAddressSpace() != space.getPhysicalSpace()) {
				throw new IllegalArgumentException(
					"Register " + register + " does not map to space " + space +
						"'s physical space (" + space.getPhysicalSpace() + ")");
			}
			return new AddressRangeImpl(
				space.getOverlayAddress(result.getMinAddress()),
				space.getOverlayAddress(result.getMaxAddress()));
		}
		if (result.getAddressSpace() != space) {
			throw new IllegalArgumentException(
				"Memory-mapped register " + register + " does not map to space " + space);
		}
		return result;
	}

	default List<String> listRegNames(Register register) {
		Set<String> result = new LinkedHashSet<>();
		result.add(register.getName());
		result.add(register.getName().toUpperCase());
		result.add(register.getName().toLowerCase());
		for (String alias : register.getAliases()) {
			result.add(alias);
			result.add(alias.toUpperCase());
			result.add(alias.toLowerCase());
		}
		return List.copyOf(result);
	}

View on GitHub (pinned to d5f144c24d)

Solutions

1. Pass the exact AddressSpace that the register's host mapping resolves into — check mapGuestToHost output's address space first.
2. Pass null for 'space' to bypass the space check and get the raw host-mapped range.
3. Re-derive the correct space from the register itself: register.getAddressSpace() for memory-mapped registers.

Example fix

// before
AddressRange range = platform.getConventionalRegisterRange(requestedSpace, memMappedRegister);

// after — use the register's own space or null
AddressRange range = platform.getConventionalRegisterRange(
    memMappedRegister.getAddressSpace(), memMappedRegister);
// or simply: platform.getConventionalRegisterRange(null, memMappedRegister);

// For memory-mapped registers, verify space matches before calling
if (!register.getAddressSpace().isRegisterSpace() && space != null) {
    if (register.getAddressSpace() != space) {
        // Use register's own space or null
        return platform.getConventionalRegisterRange(null, register);
    }
}
return platform.getConventionalRegisterRange(space, register);

static boolean memMappedRegisterSpaceOk(Register register, AddressSpace space) {
    if (space == null) return true;
    if (register.getAddressSpace().isRegisterSpace()) return true; // different check path
    return register.getAddressSpace() == space;
}

try {
    return platform.getConventionalRegisterRange(space, register);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Memory-mapped register")) {
        return platform.getConventionalRegisterRange(null, register);
    }
    throw e;
}

When it happens

Trigger: Calling getConventionalRegisterRange(space, register) where register.getAddressSpace().isRegisterSpace() is false (i.e., a memory-mapped register) and mapGuestToHost placed the register's range into a different AddressSpace than 'space'. Common when a peripheral register is memory-mapped in one space but the caller passes a different memory space.

Common situations: Passing the wrong AddressSpace for a memory-mapped/peripheral register; register mappings changed between guest language versions; overlay space confusion where the overlay's base space differs from the register's mapped space.

Related errors

• Register {register} does not map to space {space}'s physical
• Given register is not mapped to the host, or it's not in the
• Could unit would extend beyond address space
• Code unit would extend beyond address space
• Space does not exist

AI-assisted analysis of NationalSecurityAgency/ghidra@d5f144c24d (2026-08-14). Data as JSON: /api/errors/c5686e60c51e0ddb. Report an issue: GitHub.