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
)

emu

x86_64_emulator&

Reference to the CPU emulator instance

memory

memory_manager&

Reference to the memory manager for allocations

clock

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
)

emu

x86_64_emulator&

CPU emulator instance

memory

memory_manager&

Memory manager for virtual address space

registry

registry_manager&

Windows registry emulation

file_system

file_system&

Virtual file system for path translation

version

windows_version_manager&

Windows version information provider

app_settings

const application_settings&

Application-specific configuration

executable

const mapped_module&

The main executable module

ntdll

const mapped_module&

The ntdll.dll module

apiset_container

const apiset::container&

API set schema container for module redirection

ntdll32

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

memory_manager&

Memory manager for thread stack allocation

start_address

uint64_t

Entry point address for the thread

argument

uint64_t

Parameter passed to the thread function

stack_size

uint64_t

Size of the thread stack in bytes

create_flags

uint32_t

Thread creation flags (e.g., CREATE_SUSPENDED)

initial_thread

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.

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.

name

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.

name

const std::u16string&

The atom name to delete (first overload)

atom_id

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.

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

registry_manager&

Registry manager to read KnownDLLs list

file_system

const file_system&

File system for resolving DLL paths

apiset

const apiset_map&

API set schema for module redirection

system_root

const windows_path&

Windows system directory path

is_32bit

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.

name

const std::u16string&

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

is_32bit

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

is_wow64_process

bool

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

Process State

exit_status

std::optional<NTSTATUS>

Process exit status code (set when process terminates)

Memory Structures

peb64

emulator_object<PEB64>

64-bit Process Environment Block

process_params64

emulator_object<RTL_USER_PROCESS_PARAMETERS64>

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

peb32

std::optional<emulator_object<PEB32>>

32-bit PEB for WOW64 processes

process_params32

std::optional<emulator_object<RTL_USER_PROCESS_PARAMETERS32>>

32-bit process parameters for WOW64

Critical Addresses

ntdll_image_base

uint64_t

Base address of ntdll.dll

ldr_initialize_thunk

uint64_t

Address of LdrInitializeThunk (thread entry point)

rtl_user_thread_start

uint64_t

Address of RtlUserThreadStart

ki_user_apc_dispatcher

uint64_t

Address of KiUserApcDispatcher

ki_user_exception_dispatcher

uint64_t

Address of KiUserExceptionDispatcher

Handle Stores

events

handle_store<handle_types::event, event>

Event object handle store

files

handle_store<handle_types::file, file>

File handle store

sections

handle_store<handle_types::section, section>

Section object handle store

devices

handle_store<handle_types::device, io_device_container>

Device handle store

semaphores

handle_store<handle_types::semaphore, semaphore>

Semaphore handle store

threads

handle_store<handle_types::thread, emulator_thread>

Thread handle store

windows

user_handle_store<handle_types::window, window>

Window handle store (user-mode handles)

desktops

handle_store<handle_types::desktop, desktop>

Desktop handle store

Thread Management

active_thread

emulator_thread*

Pointer to the currently executing thread

spawned_thread_count

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

Build docs developers (and LLMs) love

Core API

Components

Documentation Index

​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

Build docs developers (and LLMs) love

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