# How the CpuDispatcher Orchestrates Execution with Import Stubs in SharpEmu

> Discover how SharpEmu's CpuDispatcher uses import stubs to orchestrate guest execution. It prepares the CPU context, maps stubs, and resolves imported calls via the native backend.

- Repository: [Berk/sharpemu](https://github.com/par274/sharpemu)
- Tags: internals
- Published: 2026-07-16

---

**The CpuDispatcher prepares the guest CPU context, constructs a mutable import-stub mapping table, and delegates to the native backend to resolve imported function calls during guest execution.**

The CpuDispatcher in SharpEmu serves as the central orchestrator for launching guest code. It bridges the high-level emulator entry points with the native execution backend by preparing memory regions, initializing CPU registers, and managing a dictionary that maps import stub addresses to runtime routine names.

## Entry Point Handling and Context Preparation

Execution begins when the emulator calls `DispatchEntry` in [`src/SharpEmu.Core/Cpu/CpuDispatcher.cs`](https://github.com/par274/sharpemu/blob/main/src/SharpEmu.Core/Cpu/CpuDispatcher.cs) (lines 82‑89). This public method accepts an optional `importStubs` dictionary from the caller, which maps guest virtual addresses to runtime stub identifiers (NIDs). The dispatcher immediately forwards this dictionary to the private `DispatchEntryCore` routine.

Inside `DispatchEntryCore`, the dispatcher prepares the execution environment by mapping three critical memory regions:

- **Stack space** for guest execution
- **Thread-local storage (TLS)** respecting the `TlsPrefixSize` defined in [`GuestTlsTemplate.cs`](https://github.com/par274/sharpemu/blob/main/GuestTlsTemplate.cs)
- A **return‑to‑host** stub region that allows the guest to safely exit back to the emulator

Following the memory mapping, the method creates a `CpuContext` instance and initializes its registers (lines 184‑190). This context object encapsulates the complete CPU state that the native backend will execute.

## Building the Import-Stub Mapping Table

Before handing control to the native layer, the dispatcher constructs a mutable working copy of the import stub map. As implemented in lines 14‑16 of [`CpuDispatcher.cs`](https://github.com/par274/sharpemu/blob/main/CpuDispatcher.cs):

```csharp
var effectiveImportStubs = importStubs is null
    ? new Dictionary<ulong, string>()
    : new Dictionary<ulong, string>(importStubs);

```

This `effectiveImportStubs` dictionary serves as the authoritative lookup table during execution. The dispatcher creates a mutable copy because the bootstrap payload installation may need to inject additional entries dynamically.

## Injecting Bootstrap Payload Stubs

When the entry point appears to be the start of a bootstrap payload, `TryInstallBootstrapPayload` (lines 33‑39) executes automatically. This routine performs specialized setup:

1. Maps a **bootstrap stub** region and a **payload** region into guest memory
2. Writes a small bridge stub that transitions between the bootstrap code and the host runtime
3. **Adds two entries** to `effectiveImportStubs` that map the stub addresses to `RuntimeStubNids.BootstrapBridge` (lines 63‑65)

The injection ensures that when the guest code calls these specific addresses, the native backend interprets them as requests to execute the bootstrap bridge routine rather than attempting to execute unmapped guest code.

## Native Backend Execution and Resolution

With the context prepared and the stub map finalized, the dispatcher invokes the native execution layer. At lines 75‑83, the code calls:

```csharp
var executionResult = _nativeCpuBackend.TryExecute(
    cpuContext,
    effectiveImportStubs,
    runtimeSymbols);

```

The `DirectExecutionBackend` (defined in [`src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.cs`](https://github.com/par274/sharpemu/blob/main/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.cs)) consumes this data to drive actual CPU execution. When the running guest code encounters a `call` instruction targeting an imported function, the backend pauses execution and resolves the import by looking up the current instruction pointer (RIP) in the `effectiveImportStubs` dictionary. The value retrieved—such as `RuntimeStubNids.ScePthreadCreate` or `RuntimeStubNids.SceAudioOutOpen`—tells the backend which high-level runtime routine to invoke.

## Execution Result Handling

After the native backend returns, the dispatcher evaluates the result at lines 105‑112. If `TryExecute` succeeds, the dispatcher records a successful `CpuSessionSummary`. If the backend encounters an unimplemented instruction or an unresolved import—meaning the RIP was not present in the stub map—the dispatcher generates a `CpuNotImplementedInfo` object that references the missing import handling, enabling developers to identify which stubs require implementation.

## Summary

- **DispatchEntry** receives the optional `importStubs` dictionary and forwards it to the core dispatch routine.
- **DispatchEntryCore** creates a mutable `effectiveImportStubs` copy and prepares the `CpuContext` with mapped stack, TLS, and return-to-host regions.
- **TryInstallBootstrapPayload** optionally injects bootstrap bridge entries into the stub map when the entry point indicates a payload header.
- **DirectExecutionBackend** uses the stub map to resolve every imported call by looking up the guest RIP and translating it to a runtime routine name defined in [`RuntimeStubNids.cs`](https://github.com/par274/sharpemu/blob/main/RuntimeStubNids.cs).

## Frequently Asked Questions

### What is the role of the importStubs dictionary in SharpEmu?

The `importStubs` dictionary acts as a translation layer between guest virtual addresses and host runtime services. It maps a specific memory address—where the guest expects to find an imported function—to a string identifier (NID) that the native backend recognizes, such as `RuntimeStubNids.ScePthreadCreate`. Without this mapping, the backend cannot resolve external calls and will generate a `CpuNotImplementedInfo` error.

### How does the CpuDispatcher handle bootstrap payloads?

When `DispatchEntryCore` detects a bootstrap payload header, it calls `TryInstallBootstrapPayload` (lines 33‑39). This method maps additional memory regions for the bootstrap code and injects two entries into the `effectiveImportStubs` dictionary (lines 63‑65). These entries point specific stub addresses to `RuntimeStubNids.BootstrapBridge`, allowing the native backend to intercept early initialization calls and hand them off to the emulator's bootstrap bridge logic.

### Which backend consumes the import-stub mapping?

The `DirectExecutionBackend` class located in [`src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.cs`](https://github.com/par274/sharpemu/blob/main/src/SharpEmu.Core/Cpu/Native/DirectExecutionBackend.cs) consumes the mapping. During execution, it uses the dictionary to resolve every imported function call by querying the current RIP against the prepared stub table, ensuring that guest calls to runtime services are correctly redirected to the appropriate host implementations.

### What happens when an import stub is not resolved?

If the native backend encounters a call to an address that does not exist in the `effectiveImportStubs` dictionary, it cannot complete the execution. The backend returns a failure result, causing the `CpuDispatcher` to create a `CpuNotImplementedInfo` record (lines 105‑112) that identifies the missing stub, allowing developers to extend the import mapping with the required runtime routine.