Dynamic Recompiler Author's Guide

This is intended to be an introduction to how to write a dynamic recompiler using the universal architecture in MAME. It is important to note that the description of how to write a dynamic recompiler below is not the only way to do so. In fact, the universal architecture is sufficiently flexible that it is possible to do something substantially different than what is described here and still make it work.

The decription below essentially describes how the first two recompilers (MIPS3 and PowerPC) operate, and provides in general a well-tested framework for future recompilers.

I suspect this article will eventually need to be broken into multiple separate pieces, but we'll keep it all together to start with.

Logic Flow

The logic flow of an interpreter is pretty easy to understand, because it works like a CPU does:

mycpu_execute_interpreted(numcycles)
{
   do
   {
      opcode = fetch_opcode();
      execute_opcode(opcode);
      numcycles -= opcode_num_cycles;
   }
   while (numcycles >= 0);
}

Essentially, the core execution of the interpreter consists of sitting in a loop, fetching a single opcode at a time, executing it, and counting up cycles until it is time to move on to something else in the emulation. The bulk of the code in an interpreter consists of the implementations of the individual opcodes, and must be relatively well-tuned because it is executed quite frequently.

In contrast, the logic flow of a dynamic recompiler is considerably less analagous to a CPU:

mycpu_execute_recompiled(numcycles)
{
   cpustate.numcycles = numcycles;
   do
   {
      return_code = (*recompiler_entry_point)();
      if (return_code == EXIT_MISSING_CODE)
         recompile_code_at_current_pc();
      else if (return_code == EXIT_FLUSH_CACHE)
         code_cache_flush();
   }
   while (return_code != EXIT_OUT_OF_CYCLES);
}

This may seem kind of odd at first, but let's step through the high-level flow to understand what is happening.

The first thing we do is stash the number of cycles to execute somewhere where it will be accessible to the generated code. In this case we, store it in the CPU state. Then we begin our execution loop.

Now, in an ideal world, all the code we would ever want to execute has already been translated to the target architecture, and so to execute it, we simply jump into the translated code and begin execution. If this is in fact the case, then the generated code will execute for the number of cycles we stashed in the CPU state. When it is finished, it will return to the caller with a return code of EXIT_OUT_OF_CYCLES, indicating that all the cycles have been exhausted.

Of course, this is a dynamic recompiler. The word dynamic here refers to the fact that we do not translate all the code up front, but rather perform translation on the fly, as new code is encountered. This means that we will sometimes attempt to execute code that hasn't been translated yet. When this occurs, the translated code will return to the caller with a special return code of EXIT_MISSING_CODE, meaning that there is no valid translated code for the current PC. In response to receiving this return code, the recompiler must translate the new code into the code cache, and then call back again to the translated code to allow it to continue processing.

It is also possible that during execution, a substantial change is made to the CPU's state, such that all previously translated code is immediately invalidated. In this situation, the translated code returns EXIT_FLUSH_CACHE, in response to which the recompiler will flush the cache. When finished, we loop back around and attempt to execute the translated code again. Of course, since we just flushed the cache, the expectation is that we will immediately return with an EXIT_MISSING_CODE so that we are forced to translate from scratch the code that was previously executing.

Setup and Initialization

Initialization of an interpreted CPU core is simple: just configure the initial state of the CPU and you're done.

With a dynamic recompiler, however, there are a number of things you need to set up and configure in order to be able to dynamically generate code on the fly. This added complexity means that initialization of the CPU state itself gets buried under the details of the recompiler. For this reason, it is recommended that you create a separate "common" module which contains the actual CPU state and functions you can call to initialize and reset the state, as well as other functions that would be shared between a recompiler and an interpreter. This also means that if you decide to maintain an interpreter alongside your recompiler, some of the interpreter logic can be replaced by calls into this common code, ensuring that complicated behaviors are consistent between the two.

To explain what needs to be done during recompiler initialization, this article will walk through the MIPS3 recompiler initialization code step-by-step, explaining along the way what each part of the function is doing and why it is necessary. First, though, I want to mention one global:

static mips3_state *mips3;

The first thing to point out is that this global mips3 variable contains a pointer to the MIPS3 CPU state. The actual state structure (mips3_state) is defined in the common module which was described above. Note that unlike an interpreter, where the CPU state is typically accessed via globals for speed, for a recompiler you pretty much need to use a pointer to memory that has been specially allocated from the code cache, in order to enable your generated code quick access to the CPU state. In terms of speed, there is no benefit to a pointer versus globals, so this is not a difficult choice to make.

Now, getting into the actual initialization function:

/* allocate enough space for the cache and the core */
cache = drccache_alloc(CACHE_SIZE + sizeof(*mips3));
if (cache == NULL)
    fatalerror("Unable to allocate cache of size %d", (UINT32)(CACHE_SIZE + sizeof(*mips3)));

We first allocate our code cache. There is a helper module drccache.c which contains some basic functions for allocating and managing space within the code cache. Note that CACHE_SIZE is hard-coded (in this case, it is 32MB). This value should be large enough to ensure that you don't need to frequently flush the cache and throw away everything you've generated. In addition to the cache itself, we also allocate space for the mips3_state.

/* allocate the core memory */
mips3 = drccache_memory_alloc_near(cache, sizeof(*mips3));
memset(mips3, 0, sizeof(*mips3));

Once we have the cache, we allocate memory from it for the mips3_state. Note that we allocate this memory from the "near cache", where it can be directly accessed by the generated code.

/* initialize the core */
mips3com_init(mips3, flavor, bigendian, index, clock, config, irqcallback);

After allocating the cache, we call through to the common module's initialization function (all MIPS3 common module functions are prefixed with mips3com_), which will configure the mips3_state to the initial processor state, configure save states for the processor, and do any initial configuration.

/* allocate the implementation-specific state from the full cache */
mips3->impstate = drccache_memory_alloc_near(cache, sizeof(*mips3->impstate));
memset(mips3->impstate, 0, sizeof(*mips3->impstate));
mips3->impstate->cache = cache;

Now that the core is allocated and initialized, we allocate more "near cache" memory for the implementation-specific state. This is a structure defined at the top of the module which contains all of the recompiler-specific state that the common module has no knowledge of. Conveniently, the shared mips3_state contains a pointer member impstate which is provided specifically for the purpose of storing a pointer to our implementation-specific state. One of the most important bits of implementation-specific state is a pointer to the cache object, so we immediately store that.

UINT32 flags = 0;

/* initialize the UML generator */
if (FORCE_C_BACKEND)
    flags |= DRCUML_OPTION_USE_C;
if (LOG_UML)
    flags |= DRCUML_OPTION_LOG_UML; 
if (LOG_NATIVE)
    flags |= DRCUML_OPTION_LOG_NATIVE;

mips3->impstate->drcuml = drcuml_alloc(cache, flags, 8, 32, 2);
if (mips3->impstate->drcuml == NULL)
    fatalerror("Error initializing the UML");

At this point, we have allocated all our necessary state, so we are ready to create a new UML object, which is what allows us to generate universal machine language code on the fly. There are 5 parameters to this function, and understanding their purpose and meaning is crucial, so let's examine them one by one:

• cache is the first parameter, and it is simply a pointer to the code cache object we allocated; the UML code is specifically permitted to make use of the cache for its own needs (allocating memory, etc), and will ultimately provide the same pointer to the back-end
• flags is a set of bit flags ORed together that control the UML's behavior:
  • the DRCUML_OPTION_USE_C flag tells the UML to ignore any native back-ends that might exist and instead always use the C back-end; this is useful for debugging issues in the back-ends, so you can compare behaviors against the C back-end
  • the DRCUML_OPTION_LOG_UML flag instructs the UML to dump a disassembly of each block of UML that is generated; this disassembly is written to the file drcuml.asm in the same directory as the MAME application
  • the DRCUML_OPTION_LOG_NATIVE flag is passed down by the UML to the back-end, and tells the back-end to generate a disassembly of each block of native code generated; the name of this file is back-end specific
• modes is the third parameter (in this case 8); the concept of modes will be explained a bit farther on
• addrbits is the fourth parameter (in this case 32) and specifies the number of valid address bus bits to be used for looking up the current PC; note that this value should reflect the number of logical address bits, since the PC is looked up based on its logical address
• ignorebits is the fifth parameter (in this case 2) which specifies the number of low order bits to ignore in the current PC; in the MIPS case, for example, each instruction is exactly 4 bytes long and starts/ends on an instruction boundary; this means that the low 2 bits can be ignored when computing a unique index to look up

Given this information, the UML can allocate itself and the back-end generator, and knows how to size all of its internal structures.

/* add symbols for our stuff */
drcuml_symbol_add(mips3->impstate->drcuml, &mips3->pc, sizeof(mips3->pc), "pc");
drcuml_symbol_add(mips3->impstate->drcuml, &mips3->icount, sizeof(mips3->icount), "icount");
/* more deleted */
drcuml_symbol_add(mips3->impstate->drcuml, &mips3->impstate->mode, sizeof(mips3->impstate->mode), "mode");

Now that the UML is created, we can improve the output of our disassembly by providing symbols. For each important symbol that might be referenced by the code, its address and size are provided along with a friendly string name. Only a partial excerpt is included here, as there are quite a large number of symbols that the MIPS recompiler registers. The symbols can live anywhere, so feel free to provide as much detail as you'd like when adding symbol values.

drcfe_config feconfig =
{
    COMPILE_BACKWARDS_BYTES,     /* code window start offset = startpc - window_start */
    COMPILE_FORWARDS_BYTES,      /* code window end offset = startpc + window_end */
    COMPILE_MAX_SEQUENCE,        /* maximum instructions to include in a sequence */
    mips3fe_describe             /* callback to describe a single instruction */
};

/* initialize the front-end helper */
if (SINGLE_INSTRUCTION_MODE)
    feconfig.max_sequence = 1;
mips3->impstate->drcfe = drcfe_init(&feconfig, mips3);

Initialize front-end.

/* allocate memory for cache-local state and initialize it */
memcpy(mips3->impstate->fpmode, fpmode_source, sizeof(fpmode_source));

Copy tables.

/* compute the register parameters */
for (regnum = 0; regnum < 34; regnum++)
{
    mips3->impstate->regmap[regnum].type = (regnum == 0) ? DRCUML_PTYPE_IMMEDIATE : DRCUML_PTYPE_MEMORY;
    mips3->impstate->regmap[regnum].value = (regnum == 0) ? 0 : (FPTR)&mips3->r[regnum];
    mips3->impstate->regmaplo[regnum].type = (regnum == 0) ? DRCUML_PTYPE_IMMEDIATE : DRCUML_PTYPE_MEMORY;
    mips3->impstate->regmaplo[regnum].value = (regnum == 0) ? 0 : (FPTR)LOPTR(&mips3->r[regnum]);
}

/* if we have registers to spare, assign r2, r3, r4 to leftovers */
if (!DISABLE_FAST_REGISTERS)
{
    drcuml_get_backend_info(mips3->impstate->drcuml, &beinfo);
    if (beinfo.direct_iregs > 4)
    {
        mips3->impstate->regmap[2].type = mips3->impstate->regmaplo[2].type = DRCUML_PTYPE_INT_REGISTER;
        mips3->impstate->regmap[2].value = mips3->impstate->regmaplo[2].value = DRCUML_REG_I4;
    }
    if (beinfo.direct_iregs > 5)
    {
        mips3->impstate->regmap[3].type = mips3->impstate->regmaplo[3].type = DRCUML_PTYPE_INT_REGISTER;
        mips3->impstate->regmap[3].value = mips3->impstate->regmaplo[3].value = DRCUML_REG_I5;
    }
    if (beinfo.direct_iregs > 6)
    {
        mips3->impstate->regmap[4].type = mips3->impstate->regmaplo[4].type = DRCUML_PTYPE_INT_REGISTER;
        mips3->impstate->regmap[4].value = mips3->impstate->regmaplo[4].value = DRCUML_REG_I6;
    }
}

Configure registers.

/* mark the cache dirty so it is updated on next execute */
mips3->impstate->cache_dirty = TRUE;

Mark cache dirty.