An emulated function stops with an unmapped memory read, write or fetch

Symptoms

A call under GameFrame's emulators stops with UC_ERR_READ_UNMAPPED, UC_ERR_WRITE_UNMAPPED or UC_ERR_FETCH_UNMAPPED ("Invalid memory read"), and pe32_emu prints bad memory access at ADDRESS from EIP.

Cause

The function reached memory the emulator never set up. The usual reasons, from the case studies (observed):

• a pointer field of an input structure that the test did not fill, or a global that the game's loader or DllMain sets, which the emulator does not run;
• the C runtime's thread data: sprintf and similar library calls read FS or GS, and pe32_emu maps no TEB (POD's Watcom sprintf);
• thread-local variables: pe_emu maps a TEB at GS, but __declspec(thread) also needs the TLS slot array at TEB+0x58;
• a fetch at a small address: a function pointer in the input that was left 0.

What to do

Read the faulting address and the instruction at EIP. A small address is a field you did not fill: find its offset in the instruction and fill it (emu.alloc and write). A global's address is a global the loader sets: write it from the original's own initialisation or a memory dump. For a library call that needs the C runtime, stop at the call with call(..., until=CALL_SITE) and read its arguments from stack. For an import, give a stub (stubs=).