process_context

The process_context class maintains the complete state of an emulated Windows process, including threads, handles, memory structures, and Windows-specific objects.

Overview

This class serves as the central hub for process-level resources in the Windows emulator. It manages:

Process Environment Block (PEB) and process parameters
Thread lifecycle and synchronization
Handle tables for kernel objects (files, events, sections, etc.)
User-mode objects (windows, desktops)
Atoms and window classes
WOW64 support for 32-bit applications

Constructor

process_context(
    x86_64_emulator& emu,
    memory_manager& memory,
    utils::clock& clock,
    callbacks& cb
)

x86_64_emulator&

Reference to the CPU emulator instance

memory_manager&

Reference to the memory manager for allocations

utils::clock&

System clock for time-related operations

callbacks&

Callback functions for thread lifecycle events

Methods

setup

Initializes the process context with all necessary Windows structures.

void setup(
    x86_64_emulator& emu,
    memory_manager& memory,
    registry_manager& registry,
    file_system& file_system,
    windows_version_manager& version,
    const application_settings& app_settings,
    const mapped_module& executable,
    const mapped_module& ntdll,
    const apiset::container& apiset_container,
    const mapped_module* ntdll32 = nullptr
)

x86_64_emulator&

CPU emulator instance

memory_manager&

Memory manager for virtual address space

registry_manager&

Windows registry emulation

file_system&

Virtual file system for path translation

windows_version_manager&

Windows version information provider

const application_settings&

Application-specific configuration

const mapped_module&

The main executable module

const mapped_module&

The ntdll.dll module

const apiset::container&

API set schema container for module redirection

const mapped_module*

default:"nullptr"

Optional 32-bit ntdll for WOW64 processes

create_thread

Creates a new emulated thread in the process.

handle create_thread(
    memory_manager& memory,
    uint64_t start_address,
    uint64_t argument,
    uint64_t stack_size,
    uint32_t create_flags,
    bool initial_thread = false
)

memory_manager&

Memory manager for thread stack allocation

uint64_t

Entry point address for the thread

uint64_t

Parameter passed to the thread function

uint64_t

Size of the thread stack in bytes

uint32_t

Thread creation flags (e.g., CREATE_SUSPENDED)

bool

default:"false"

Whether this is the process’s initial thread

Returns: A handle to the newly created thread.

Atom Management

Atoms are globally unique string identifiers used by Windows for window classes and other purposes.

find_atom

std::optional<uint16_t> find_atom(std::u16string_view name)

Searches for an existing atom by name.

std::u16string_view

The atom name to search for

Returns: The atom ID if found, or std::nullopt otherwise.

add_or_find_atom

uint16_t add_or_find_atom(std::u16string name)

Adds a new atom or returns existing one, incrementing reference count.

std::u16string

The atom name to add or find

Returns: The atom ID (new or existing).

delete_atom

bool delete_atom(const std::u16string& name)
bool delete_atom(uint16_t atom_id)

Decrements the reference count and removes the atom if it reaches zero.

const std::u16string&

The atom name to delete (first overload)

uint16_t

The atom ID to delete (second overload)

Returns: true if the atom was deleted, false otherwise.

get_atom_name

const std::u16string* get_atom_name(uint16_t atom_id) const

Retrieves the name associated with an atom ID.

uint16_t

The atom ID to look up

Returns: Pointer to the atom name, or nullptr if not found.

KnownDLLs Management

KnownDLLs are preloaded system DLLs cached as section objects.

build_knowndlls_section_table

template <typename T>
void build_knowndlls_section_table(
    registry_manager& registry,
    const file_system& file_system,
    const apiset_map& apiset,
    const windows_path& system_root,
    bool is_32bit
)

Builds the KnownDLLs section table from registry configuration.

registry_manager&

Registry manager to read KnownDLLs list

const file_system&

File system for resolving DLL paths

const apiset_map&

API set schema for module redirection

const windows_path&

Windows system directory path

bool

Whether to build 32-bit or 64-bit KnownDLLs table

get_knowndll_section_by_name

std::optional<section> get_knowndll_section_by_name(
    const std::u16string& name,
    bool is_32bit
) const

Retrieves a KnownDLL section object by name.

const std::u16string&

DLL name (e.g., “kernel32.dll”)

bool

Whether to search in 32-bit or 64-bit table

Returns: The section object if found.

add_knowndll_section

void add_knowndll_section(
    const std::u16string& name,
    const section& section,
    bool is_32bit
)

Adds a section to the KnownDLLs cache.

has_knowndll_section

bool has_knowndll_section(
    const std::u16string& name,
    bool is_32bit
) const

Checks if a KnownDLL section exists.

get_handle_store

generic_handle_store* get_handle_store(handle handle)

Retrieves the appropriate handle store for a given handle.

handle

The handle to look up

Returns: Pointer to the handle store, or nullptr if not found.

get_live_thread_count

size_t get_live_thread_count() const

Returns: The number of currently active threads.

Serialization

void serialize(utils::buffer_serializer& buffer) const
void deserialize(utils::buffer_deserializer& buffer)

Serialization support for saving/loading process state.

Public Members

WOW64 Support

bool

Flag indicating if this is a 32-bit process running under WOW64

Process State

std::optional<NTSTATUS>

Process exit status code (set when process terminates)

Memory Structures

emulator_object<PEB64>

64-bit Process Environment Block

emulator_object<RTL_USER_PROCESS_PARAMETERS64>

64-bit process parameters (command line, environment, etc.)

std::optional<emulator_object<PEB32>>

32-bit PEB for WOW64 processes

std::optional<emulator_object<RTL_USER_PROCESS_PARAMETERS32>>

32-bit process parameters for WOW64

Critical Addresses

uint64_t

Base address of ntdll.dll

uint64_t

Address of LdrInitializeThunk (thread entry point)

uint64_t

Address of RtlUserThreadStart

uint64_t

Address of KiUserApcDispatcher

uint64_t

Address of KiUserExceptionDispatcher

Handle Stores

handle_store<handle_types::event, event>

Event object handle store

handle_store<handle_types::file, file>

File handle store

handle_store<handle_types::section, section>

Section object handle store

handle_store<handle_types::device, io_device_container>

Device handle store

handle_store<handle_types::semaphore, semaphore>

Semaphore handle store

handle_store<handle_types::thread, emulator_thread>

Thread handle store

user_handle_store<handle_types::window, window>

Window handle store (user-mode handles)

handle_store<handle_types::desktop, desktop>

Desktop handle store

Thread Management

emulator_thread*

Pointer to the currently executing thread

uint32_t

Total number of threads created

Usage Example

// Create process context
process_context::callbacks callbacks;
callbacks.on_thread_create = [](handle h, emulator_thread& thr) {
    printf("Thread created: %p\n", h.value);
};

process_context context(emu, memory, clock, callbacks);

// Setup the process
context.setup(emu, memory, registry, fs, version, settings,
              executable_module, ntdll_module, apiset);

// Create a thread
auto thread_handle = context.create_thread(
    memory,
    0x140001000,  // entry point
    0,            // argument
    0x40000,      // 256KB stack
    0,            // no special flags
    true          // initial thread
);

// Add an atom
auto atom_id = context.add_or_find_atom(u"MyWindowClass");

// Look up a handle store
if (auto* store = context.get_handle_store(some_handle)) {
    // Work with the handle store
}

Core API

Components

process_context

Overview

Constructor

Methods

setup

create_thread

Atom Management

find_atom

add_or_find_atom

delete_atom

get_atom_name

KnownDLLs Management

build_knowndlls_section_table

get_knowndll_section_by_name

add_knowndll_section

has_knowndll_section

get_handle_store

get_live_thread_count

Serialization

Public Members

WOW64 Support

Process State

Memory Structures

Critical Addresses

Handle Stores

Thread Management

Usage Example

See Also

​Overview

​Constructor

​Methods

​setup

​create_thread

​Atom Management

​find_atom

​add_or_find_atom

​delete_atom

​get_atom_name

​KnownDLLs Management

​build_knowndlls_section_table

​get_knowndll_section_by_name

​add_knowndll_section

​has_knowndll_section

​get_handle_store

​get_live_thread_count

​Serialization

​Public Members

​WOW64 Support

​Process State

​Memory Structures

​Critical Addresses

​Handle Stores

​Thread Management

​Usage Example

​See Also

Overview

Constructor

Methods

setup

create_thread

Atom Management

find_atom

add_or_find_atom

delete_atom

get_atom_name

KnownDLLs Management

build_knowndlls_section_table

get_knowndll_section_by_name

add_knowndll_section

has_knowndll_section

get_handle_store

get_live_thread_count

Serialization

Public Members

WOW64 Support

Process State

Memory Structures

Critical Addresses

Handle Stores

Thread Management

Usage Example

See Also