{"record":{"id":"c5686e60c51e0ddb","repo":"NationalSecurityAgency/ghidra","slug":"memory-mapped-register-register-does-not-map-to","errorCode":null,"errorMessage":"Memory-mapped register {register} does not map to space {space}","messagePattern":"Memory-mapped register (.+?) does not map to space (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/guest/InternalTracePlatform.java","lineNumber":78,"sourceCode":"\t\tAddressRange result = mapGuestToHost(TraceRegisterUtils.rangeForRegister(register));\n\t\tif (result == null) {\n\t\t\tthrow new IllegalArgumentException(\"Register \" + register + \" is not mapped\");\n\t\t}\n\t\tif (space == null) {\n\t\t\treturn result;\n\t\t}\n\t\tif (register.getAddressSpace().isRegisterSpace()) {\n\t\t\tif (result.getAddressSpace() != space.getPhysicalSpace()) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Register \" + register + \" does not map to space \" + space +\n\t\t\t\t\t\t\"'s physical space (\" + space.getPhysicalSpace() + \")\");\n\t\t\t}\n\t\t\treturn new AddressRangeImpl(\n\t\t\t\tspace.getOverlayAddress(result.getMinAddress()),\n\t\t\t\tspace.getOverlayAddress(result.getMaxAddress()));\n\t\t}\n\t\tif (result.getAddressSpace() != space) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\"Memory-mapped register \" + register + \" does not map to space \" + space);\n\t\t}\n\t\treturn result;\n\t}\n\n\tdefault List<String> listRegNames(Register register) {\n\t\tSet<String> result = new LinkedHashSet<>();\n\t\tresult.add(register.getName());\n\t\tresult.add(register.getName().toUpperCase());\n\t\tresult.add(register.getName().toLowerCase());\n\t\tfor (String alias : register.getAliases()) {\n\t\t\tresult.add(alias);\n\t\t\tresult.add(alias.toUpperCase());\n\t\t\tresult.add(alias.toLowerCase());\n\t\t}\n\t\treturn List.copyOf(result);\n\t}\n","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/guest/InternalTracePlatform.java#L60-L96","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the exact AddressSpace that the register's host mapping resolves into — check mapGuestToHost output's address space first.","Pass null for 'space' to bypass the space check and get the raw host-mapped range.","Re-derive the correct space from the register itself: register.getAddressSpace() for memory-mapped registers."],"exampleFix":"// before\nAddressRange range = platform.getConventionalRegisterRange(requestedSpace, memMappedRegister);\n\n// after — use the register's own space or null\nAddressRange range = platform.getConventionalRegisterRange(\n    memMappedRegister.getAddressSpace(), memMappedRegister);\n// or simply: platform.getConventionalRegisterRange(null, memMappedRegister);","handlingStrategy":"validation","validationCode":"// For memory-mapped registers, verify space matches before calling\nif (!register.getAddressSpace().isRegisterSpace() && space != null) {\n    if (register.getAddressSpace() != space) {\n        // Use register's own space or null\n        return platform.getConventionalRegisterRange(null, register);\n    }\n}\nreturn platform.getConventionalRegisterRange(space, register);","typeGuard":"static boolean memMappedRegisterSpaceOk(Register register, AddressSpace space) {\n    if (space == null) return true;\n    if (register.getAddressSpace().isRegisterSpace()) return true; // different check path\n    return register.getAddressSpace() == space;\n}","tryCatchPattern":"try {\n    return platform.getConventionalRegisterRange(space, register);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Memory-mapped register\")) {\n        return platform.getConventionalRegisterRange(null, register);\n    }\n    throw e;\n}","preventionTips":["For memory-mapped registers, pass register.getAddressSpace() as the space argument or null.","Avoid mixing overlay spaces with memory-mapped register queries unless you've verified the mapping.","Cache mapGuestToHost results to verify expected host spaces before the API call."],"tags":["address-space","memory-mapped-register","guest-platform","trace-modeling"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}