vmi_os_windows/

lib.rs

//! # Windows OS-specific VMI operations
//!
//! This crate provides functionality for introspecting Windows-based
//! virtual machines, working in conjunction with the `vmi-core` crate.
//! It offers abstractions and utilities for navigating Windows kernel
//! structures, analyzing processes and memory, and performing Windows-specific
//! VMI tasks.
//!
//! ## Features
//!
//! - Windows kernel structure parsing and navigation
//! - Process and thread introspection
//! - Memory management operations (VAD tree traversal, PFN database manipulation)
//! - Windows object handling (files, sections, etc.)
//! - PE file format parsing and analysis
//!
//! ## Safety Considerations
//!
//! Many operations in this crate require pausing the VM to ensure consistency.
//! Always pause the VM when performing operations that could be affected by
//! concurrent changes in the guest OS. Be aware of the Windows version you're
//! introspecting, as kernel structures may vary between versions. Handle errors
//! appropriately, as VMI operations can fail due to various reasons (e.g.,
//! invalid memory access, incompatible Windows version).
//!
//! ## Examples
//!
//! ```no_run
//! # use vmi::{
//! #     VmiCore,
//! #     arch::amd64::Amd64,
//! #     driver::VmiVmControl,
//! #     os::windows::WindowsOs,
//! # };
//! #
//! # fn example<Driver>(
//! #     vmi: &VmiCore<Driver>,
//! #     _os: &WindowsOs<Driver>
//! # ) -> Result<(), Box<dyn std::error::Error>>
//! # where
//! #     Driver: VmiVmControl<Architecture = Amd64>,
//! # {
//! let _guard = vmi.pause_guard()?;
//! // Perform introspection operations here
//! // VM automatically resumes when `_guard` goes out of scope
//! # Ok(())
//! # }
//! ```
//!
//! Always consider the potential for race conditions and ensure you're
//! working with a consistent state of the guest OS.

// Allow Windows-specific naming conventions to be used throughout this module.
#![allow(
    non_snake_case,         // example: AlpcpSendMessage
    non_upper_case_globals, // example: StandbyPageList
)]

use std::{cell::RefCell, collections::HashMap};

use isr_core::Profile;
use once_cell::unsync::OnceCell;
use vmi_core::{
    AccessContext, Architecture, Gfn, Pa, Registers as _, Va, VcpuId, VmiCore, VmiDriver, VmiError,
    VmiState,
    driver::{VmiRead, VmiWrite},
    os::{ProcessObject, ThreadObject, VmiOs, VmiOsThread},
    trace::Hex,
};
use vmi_macros::derive_trait_from_impl;
use zerocopy::{FromBytes, IntoBytes};

mod arch;
pub use self::arch::{
    ArchAdapter, CONTEXT_AMD64, CONTEXT_X86, FLOATING_SAVE_AREA, KDESCRIPTOR_AMD64,
    KDESCRIPTOR_X86, KSPECIAL_REGISTERS_AMD64, KSPECIAL_REGISTERS_X86, M128A,
    MAXIMUM_SUPPORTED_EXTENSION, SIZE_OF_80387_REGISTERS, StructLayout, StructLayout32,
    StructLayout64, WindowsContext, WindowsExceptionVector, WindowsInterrupt,
    WindowsPageTableEntry, WindowsRegistersAdapter, WindowsSpecialRegisters, XSAVE_FORMAT,
};

mod error;
pub use self::error::WindowsError;

mod iter;
pub use self::iter::{
    DirectoryObjectIterator, HandleTableEntryIterator, KeyControlBlockIterator, KeyNodeIterator,
    KeyValueIterator, ListEntry, ListEntryIterator, ListEntryIteratorBase, ListEntryLayout,
    TreeNodeIterator,
};

pub mod pe;
pub use self::pe::{CodeView, PeError, PeFile, PeHeader, PeImage, PeImageExt};

pub mod unwind;

mod offsets;
pub use self::offsets::{Offsets, OffsetsExt, Symbols}; // TODO: make private + remove offsets() & symbols() methods

mod comps;
pub use self::comps::{
    CurDir, CurDirLayout, FromWindowsObject, LdrDataTableEntry, LdrDataTableEntryLayout,
    ParseObjectTypeError, Peb, PebLayout, PebLdrData, PebLdrDataLayout, RtlUserProcessParameters,
    RtlUserProcessParametersLayout, Teb, TebLayout, WOW64_TLS_APCLIST, WOW64_TLS_CPURESERVED,
    WOW64_TLS_FILESYSREDIR, WOW64_TLS_TEMPLIST, WOW64_TLS_USERCALLBACKDATA, WOW64_TLS_WOW64INFO,
    WindowsControlArea, WindowsDirectoryObject, WindowsFileObject, WindowsHandleTable,
    WindowsHandleTableEntry, WindowsHive, WindowsHiveBaseBlock, WindowsHiveCellIndex,
    WindowsHiveMapDirectory, WindowsHiveMapEntry, WindowsHiveMapTable, WindowsHiveStorageType,
    WindowsImage, WindowsImpersonationLevel, WindowsKernelProcessorBlock, WindowsKeyControlBlock,
    WindowsKeyIndex, WindowsKeyNode, WindowsKeyValue, WindowsKeyValueData, WindowsKeyValueFlags,
    WindowsKeyValueType, WindowsLuid, WindowsModule, WindowsObject, WindowsObjectAttributes,
    WindowsObjectHeaderNameInfo, WindowsObjectType, WindowsObjectTypeKind, WindowsPeb,
    WindowsPebBase, WindowsPebLdrData, WindowsPebLdrDataBase, WindowsPrivilege, WindowsProcess,
    WindowsProcessParameters, WindowsProcessParametersBase, WindowsProcessorMode, WindowsRegion,
    WindowsSectionObject, WindowsSegment, WindowsSession, WindowsSid, WindowsSidAndAttributes,
    WindowsSidAttributes, WindowsTeb, WindowsTebBase, WindowsThread, WindowsThreadState,
    WindowsThreadWaitReason, WindowsToken, WindowsTokenFlags, WindowsTokenPrivilege,
    WindowsTokenSource, WindowsTokenType, WindowsTrapFrame, WindowsUnloadedDriver,
    WindowsUserModule, WindowsUserModuleBase, WindowsWow64Kind,
};

/// VMI operations for the Windows operating system.
///
/// `WindowsOs` provides methods and utilities for introspecting a Windows-based
/// virtual machine. It encapsulates Windows-specific knowledge and operations,
/// allowing for high-level interactions with the guest OS structures and processes.
///
/// # Usage
///
/// Create an instance of [`WindowsOs`] using a [`Profile`] that contains information
/// about the specific Windows version being introspected:
///
/// ```no_run
/// use isr::cache::IsrCache;
/// use vmi::{
///     VcpuId, VmiCore,
///     arch::amd64::Amd64,
///     driver::{VmiQueryRegisters, VmiRead, VmiVmControl},
///     os::windows::WindowsOs,
/// };
///
/// # fn example<Driver>(
/// #     driver: Driver
/// # ) -> Result<(), Box<dyn std::error::Error>>
/// # where
/// #     Driver: VmiRead<Architecture = Amd64>
/// #           + VmiQueryRegisters<Architecture = Amd64>
/// #           + VmiVmControl<Architecture = Amd64>,
/// # {
/// // Setup VMI.
/// let core = VmiCore::new(driver)?;
///
/// // Try to find the kernel information.
/// // This is necessary in order to load the profile.
/// let kernel_info = {
///     let _guard = core.pause_guard()?;
///     let registers = core.registers(VcpuId(0))?;
///
///     WindowsOs::find_kernel(&core, &registers)?.expect("kernel information")
/// };
///
/// // Load the profile using the ISR library.
/// let isr = IsrCache::new("cache")?;
/// let entry = isr.entry_from_codeview(kernel_info.codeview)?;
/// let profile = entry.profile()?;
///
/// // Create a new `WindowsOs` instance.
/// let os = WindowsOs::<Driver>::new(&profile)?;
/// # Ok(())
/// # }
/// ```
///
/// # Important Notes
///
/// - Many methods of this struct require pausing the VM to ensure consistency.
///   Use [`pause_guard`] when performing operations that might be affected
///   by concurrent changes in the guest OS.
///
/// - The behavior and accuracy of some methods may vary depending on the
///   Windows version being introspected. Always ensure your [`Profile`] matches
///   the guest OS version.
///
/// # Examples
///
/// Retrieving information about the current process:
///
/// ```no_run
/// # use vmi::{
/// #     VmiState,
/// #     arch::amd64::Amd64,
/// #     driver::VmiRead,
/// #     os::{VmiOsProcess as _, windows::WindowsOs},
/// # };
/// #
/// # fn example<Driver>(
/// #     vmi: &VmiState<WindowsOs<Driver>>,
/// # ) -> Result<(), Box<dyn std::error::Error>>
/// # where
/// #     Driver: VmiRead<Architecture = Amd64>,
/// # {
/// let process = vmi.os().current_process()?;
/// let process_id = process.id()?;
/// let process_name = process.name()?;
/// println!("Current process: {} (PID: {})", process_name, process_id);
/// # Ok(())
/// # }
/// ```
///
/// Enumerating all processes:
///
/// ```no_run
/// # use vmi::{
/// #     VmiState,
/// #     arch::amd64::Amd64,
/// #     driver::VmiRead,
/// #     os::{VmiOsProcess as _, windows::WindowsOs},
/// # };
/// #
/// # fn example<Driver>(
/// #     vmi: &VmiState<WindowsOs<Driver>>,
/// # ) -> Result<(), Box<dyn std::error::Error>>
/// # where
/// #     Driver: VmiRead<Architecture = Amd64>,
/// # {
/// for process in vmi.os().processes()? {
///     let process = process?;
///     println!("Process: {} (PID: {})", process.name()?, process.id()?);
/// }
/// # Ok(())
/// # }
/// ```
///
/// # Safety
///
/// While this struct doesn't use unsafe code directly, many of its methods
/// interact with raw memory of the guest OS. Incorrect usage can lead to
/// invalid memory access or misinterpretation of data. Always ensure you're
/// working with the correct memory regions and OS structures.
///
/// [`pause_guard`]: VmiCore::pause_guard
pub struct WindowsOs<Driver>
where
    Driver: VmiDriver,
{
    offsets: Offsets,
    symbols: Symbols,

    kernel_image_base: OnceCell<Va>,
    highest_user_address: OnceCell<Va>,
    object_root_directory: OnceCell<Va>, // _OBJECT_DIRECTORY*
    object_header_cookie: OnceCell<u8>,
    object_type_cache: RefCell<HashMap<WindowsObjectTypeKind, Va>>,
    object_type_rcache: RefCell<HashMap<Va, WindowsObjectTypeKind>>,
    object_type_name_cache: RefCell<HashMap<Va, String>>,

    ke_number_processors: OnceCell<u16>,   // CCHAR
    ki_processor_block: OnceCell<Vec<Va>>, // _KPRCB*[]
    ki_kva_shadow: OnceCell<bool>,
    mm_pfn_database: OnceCell<Va>,     // _MMPFN*
    mm_unloaded_drivers: OnceCell<Va>, // _UNLOADED_DRIVERS*
    nt_build_number: OnceCell<u32>,    // ULONG
    nt_build_lab: OnceCell<String>,
    nt_build_lab_ex: OnceCell<String>,
    ps_idle_process: OnceCell<Va>, // _EPROCESS*

    _marker: std::marker::PhantomData<Driver>,
}

/// Information about the Windows kernel image.
#[derive(Debug)]
pub struct WindowsKernelInformation {
    /// Base virtual address where the kernel image is loaded.
    pub base_address: Va,

    /// Major version number of the Windows kernel.
    pub version_major: u16,

    /// Minor version number of the Windows kernel.
    pub version_minor: u16,

    /// CodeView debugging information for the kernel image.
    pub codeview: CodeView,
}

/// Represents a `_EXCEPTION_RECORD` structure.
#[derive(Debug)]
pub struct WindowsExceptionRecord {
    /// The `ExceptionCode` field of the exception record.
    ///
    /// The reason the exception occurred. This is the code generated by a
    /// hardware exception, or the code specified in the `RaiseException`
    /// function for a software-generated exception.
    pub code: u32,

    /// The `ExceptionFlags` field of the exception record.
    ///
    /// This member contains zero or more exception flags.
    pub flags: u32,

    /// The `ExceptionRecord` field of the exception record.
    ///
    /// A pointer to an associated `EXCEPTION_RECORD` structure.
    /// Exception records can be chained together to provide additional
    /// information when nested exceptions occur.
    pub record: Va,

    /// The `ExceptionAddress` field of the exception record.
    ///
    /// The address where the exception occurred.
    pub address: Va,

    /// The `ExceptionInformation` field of the exception record.
    ///
    /// An array of additional arguments that describe the exception.
    /// The number of elements in the array is determined by the `NumberParameters`
    /// field of the exception record.
    pub information: Vec<u64>,
}

macro_rules! offset {
    ($vmi:expr, $field:ident) => {
        &$vmi.underlying_os().offsets.$field
    };
}

pub(crate) use offset;

macro_rules! offset_ext_v1 {
    ($vmi:expr, $field:ident) => {
        match $vmi.underlying_os().offsets.ext() {
            Some($crate::offsets::OffsetsExt::V1(offsets)) => &offsets.$field,
            _ => unreachable!(),
        }
    };
}

pub(crate) use offset_ext_v1;

macro_rules! offset_ext_v2 {
    ($vmi:expr, $field:ident) => {
        match $vmi.underlying_os().offsets.ext() {
            Some($crate::offsets::OffsetsExt::V2(offsets)) => &offsets.$field,
            _ => unreachable!(),
        }
    };
}

pub(crate) use offset_ext_v2;

macro_rules! symbol {
    ($vmi:expr, $field:ident) => {
        $vmi.underlying_os().symbols.$field
    };
}

pub(crate) use symbol;

macro_rules! this {
    ($vmi:expr) => {
        $vmi.underlying_os()
    };
}

#[derive_trait_from_impl(WindowsOsExt)]
#[expect(non_snake_case, non_upper_case_globals)]
impl<Driver> WindowsOs<Driver>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    /// 32-bit current process pseudo-handle (-1).
    pub const NtCurrentProcess32: u64 = 0xffff_ffff;

    /// 64-bit current process pseudo-handle (-1).
    pub const NtCurrentProcess64: u64 = 0xffff_ffff_ffff_ffff;

    /// 32-bit current thread pseudo-handle (-2).
    pub const NtCurrentThread32: u64 = 0xffff_fffe;

    /// 64-bit current thread pseudo-handle (-2).
    pub const NtCurrentThread64: u64 = 0xffff_ffff_ffff_fffe;

    /// Creates a new `WindowsOs` instance.
    pub fn new(profile: &Profile) -> Result<Self, VmiError> {
        Self::create(profile, OnceCell::new())
    }

    /// Creates a new `WindowsOs` instance with a known kernel base address.
    pub fn with_kernel_base(profile: &Profile, kernel_base: Va) -> Result<Self, VmiError> {
        Self::create(profile, OnceCell::with_value(kernel_base))
    }

    fn create(profile: &Profile, kernel_image_base: OnceCell<Va>) -> Result<Self, VmiError> {
        Ok(Self {
            offsets: Offsets::new(profile)?,
            symbols: Symbols::new(profile)?,
            kernel_image_base,
            highest_user_address: OnceCell::new(),
            object_root_directory: OnceCell::new(),
            object_header_cookie: OnceCell::new(),
            object_type_cache: RefCell::new(HashMap::new()),
            object_type_rcache: RefCell::new(HashMap::new()),
            object_type_name_cache: RefCell::new(HashMap::new()),
            ke_number_processors: OnceCell::new(),
            ki_processor_block: OnceCell::new(),
            ki_kva_shadow: OnceCell::new(),
            mm_pfn_database: OnceCell::new(),
            mm_unloaded_drivers: OnceCell::new(),
            nt_build_number: OnceCell::new(),
            nt_build_lab: OnceCell::new(),
            nt_build_lab_ex: OnceCell::new(),
            ps_idle_process: OnceCell::new(),
            _marker: std::marker::PhantomData,
        })
    }

    /// Returns a reference to the Windows-specific memory offsets.
    pub fn offsets(vmi: VmiState<'_, Self>) -> &Offsets {
        &this!(vmi).offsets
    }

    /// Returns a reference to the Windows-specific symbols.
    pub fn symbols(vmi: VmiState<'_, Self>) -> &Symbols {
        &this!(vmi).symbols
    }

    /// Locates the Windows kernel in memory based on the CPU registers.
    /// This function is architecture-specific.
    ///
    /// On AMD64, the kernel is located by taking the `MSR_LSTAR` value and
    /// reading the virtual memory page by page backwards until the `MZ` header
    /// is found.
    pub fn find_kernel(
        vmi: &VmiCore<Driver>,
        registers: &<Driver::Architecture as Architecture>::Registers,
    ) -> Result<Option<WindowsKernelInformation>, VmiError> {
        Driver::Architecture::find_kernel(vmi, registers)
    }

    /// Returns the kernel build number.
    ///
    /// # Notes
    ///
    /// The value is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `NtBuildNumber` symbol.
    pub fn kernel_build_number(vmi: VmiState<Self>) -> Result<u32, VmiError> {
        this!(vmi)
            .nt_build_number
            .get_or_try_init(|| {
                let NtBuildNumber = symbol!(vmi, NtBuildNumber);

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                vmi.read_u32(kernel_image_base + NtBuildNumber)
            })
            .cloned()
    }

    /// Returns the kernel information string.
    ///
    /// # Notes
    ///
    /// The kernel information string is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `NtBuildLab` symbol.
    pub fn kernel_information_string_ex(vmi: VmiState<Self>) -> Result<Option<String>, VmiError> {
        let NtBuildLabEx = match symbol!(vmi, NtBuildLabEx) {
            Some(offset) => offset,
            None => return Ok(None),
        };

        Ok(Some(
            this!(vmi)
                .nt_build_lab_ex
                .get_or_try_init(|| {
                    let kernel_image_base = Self::kernel_image_base(vmi)?;
                    vmi.read_string(kernel_image_base + NtBuildLabEx)
                })
                .cloned()?,
        ))
    }

    /// Checks if the given handle is a kernel handle.
    ///
    /// A kernel handle is a handle with the highest bit set.
    pub fn is_kernel_handle(vmi: VmiState<Self>, handle: u64) -> Result<bool, VmiError> {
        const KERNEL_HANDLE_MASK32: u64 = 0x8000_0000;
        const KERNEL_HANDLE_MASK64: u64 = 0xffff_ffff_8000_0000;

        match vmi.registers().address_width() {
            4 => Ok(handle & KERNEL_HANDLE_MASK32 == KERNEL_HANDLE_MASK32),
            8 => Ok(handle & KERNEL_HANDLE_MASK64 == KERNEL_HANDLE_MASK64),
            _ => Err(VmiError::InvalidAddressWidth),
        }
    }

    /// Returns the lowest user-mode address.
    ///
    /// This method returns a constant value (0x10000) representing the lowest
    /// address that can be used by user-mode applications in Windows.
    ///
    /// # Notes
    ///
    /// * Windows creates a `NO_ACCESS` VAD (Virtual Address Descriptor) for the first 64KB
    ///   of virtual memory. This means the VA range 0-0x10000 is off-limits for usage.
    /// * This behavior is consistent across all Windows versions from XP through
    ///   recent Windows 11, and applies to x86, x64, and ARM64 architectures.
    /// * Many Windows APIs leverage this fact to determine whether an input argument
    ///   is a pointer or not. Here are two notable examples:
    ///
    ///   1. The `FindResource()` function accepts an `lpName` parameter of type `LPCTSTR`,
    ///      which can be either:
    ///      - A pointer to a valid string
    ///      - A value created by `MAKEINTRESOURCE(ID)`
    ///
    ///         This allows `FindResource()` to accept `WORD` values (unsigned shorts) with
    ///         a maximum value of 0xFFFF, distinguishing them from valid memory addresses.
    ///
    ///   2. The `AddAtom()` function similarly accepts an `lpString` parameter of type `LPCTSTR`.
    ///      This parameter can be:
    ///      - A pointer to a null-terminated string (max 255 bytes)
    ///      - An integer atom converted using the `MAKEINTATOM(ID)` macro
    ///
    ///   In both cases, the API can distinguish between valid pointers (which will be
    ///   above 0x10000) and integer values (which will be below 0x10000), allowing
    ///   for flexible parameter usage without ambiguity.
    pub fn lowest_user_address(_vmi: VmiState<Self>) -> Result<Va, VmiError> {
        Ok(Va(0x10000))
    }

    /// Returns the highest user-mode address.
    ///
    /// This method reads the highest user-mode address from the Windows kernel.
    /// The value is cached after the first read for performance.
    ///
    /// # Notes
    ///
    /// This value is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `MmHighestUserAddress` symbol.
    pub fn highest_user_address(vmi: VmiState<Self>) -> Result<Va, VmiError> {
        this!(vmi)
            .highest_user_address
            .get_or_try_init(|| {
                let MmHighestUserAddress = symbol!(vmi, MmHighestUserAddress);

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                vmi.read_va_native(kernel_image_base + MmHighestUserAddress)
            })
            .copied()
    }

    /// Checks if a given address is a valid user-mode address.
    ///
    /// This method determines whether the provided address falls within
    /// the range of valid user-mode addresses in Windows.
    pub fn is_valid_user_address(vmi: VmiState<Self>, address: Va) -> Result<bool, VmiError> {
        let lowest_user_address = Self::lowest_user_address(vmi)?;
        let highest_user_address = Self::highest_user_address(vmi)?;

        Ok(address >= lowest_user_address && address <= highest_user_address)
    }

    /// Returns an iterator over recently unloaded drivers.
    ///
    /// Walks the kernel's fixed-size circular buffer of unloaded driver
    /// records, newest first. The iterator stops at the first empty slot
    /// or after the buffer's 50-entry capacity has been visited.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `MmUnloadedDrivers` and `MmLastUnloadedDriver`.
    pub fn unloaded_modules<'a>(
        vmi: VmiState<'a, Self>,
    ) -> Result<
        impl Iterator<Item = Result<WindowsUnloadedDriver<'a, Driver>, VmiError>> + use<'a, Driver>,
        VmiError,
    > {
        // Note that the value of `MmLastUnloadedDriver` is intentionally
        // not cached.
        let MmLastUnloadedDriver = symbol!(vmi, MmLastUnloadedDriver);

        let kernel_image_base = Self::kernel_image_base(vmi)?;
        let mm_last_unloaded_driver = vmi.read_u32(kernel_image_base + MmLastUnloadedDriver)?;

        let mm_unloaded_drivers = this!(vmi)
            .mm_unloaded_drivers
            .get_or_try_init(|| {
                let MmUnloadedDrivers = symbol!(vmi, MmUnloadedDrivers);

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                vmi.read_va_native(kernel_image_base + MmUnloadedDrivers)
            })
            .copied()?;

        // Hardcoded in dbgeng.dll.
        const MI_UNLOADED_DRIVERS: u32 = 50;

        // Corresponds to `_UNLOADED_DRIVERS.Name.Buffer` offset.
        const UNLOADED_DRIVERS_Name_Buffer: u64 = 0x08; // 32-bit: 0x04

        // Corresponds to `sizeof(_UNLOADED_DRIVERS)`.
        const UNLOADED_DRIVERS_sizeof: u64 = 0x28; // 32-bit: 0x18

        let mut index = mm_last_unloaded_driver;
        let mut count = 0;

        Ok(std::iter::from_fn(move || {
            if count >= MI_UNLOADED_DRIVERS {
                return None;
            }

            index = index.checked_sub(1).unwrap_or(MI_UNLOADED_DRIVERS - 1);
            count += 1;

            let va = mm_unloaded_drivers + index as u64 * UNLOADED_DRIVERS_sizeof;
            let name_buffer = match vmi.read_va_native(va + UNLOADED_DRIVERS_Name_Buffer) {
                Ok(name_buffer) => name_buffer,
                Err(err) => return Some(Err(err)),
            };

            if name_buffer.is_null() {
                return None;
            }

            Some(Ok(WindowsUnloadedDriver::new(vmi, va)))
        }))
    }

    /// Returns the number of active processors in the system.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `KeNumberProcessors`.
    pub fn number_of_processors(vmi: VmiState<Self>) -> Result<u16, VmiError> {
        this!(vmi)
            .ke_number_processors
            .get_or_try_init(|| {
                // KeNumberProcessors is a CCHAR (i8), but we return it as u16
                // for convenience since VcpuId is u16.
                let KeNumberProcessors = symbol!(vmi, KeNumberProcessors);

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                Ok(vmi.read_u8(kernel_image_base + KeNumberProcessors)? as u16)
            })
            .copied()
    }

    /// Returns the virtual address of the current Kernel Processor Control
    /// Region (KPCR).
    ///
    /// The KPCR is a per-processor data structure in Windows that contains
    /// critical information about the current processor state. This method
    /// returns the virtual address of the KPCR for the current processor.
    pub fn current_kpcr(vmi: VmiState<Self>) -> Va {
        Driver::Architecture::current_kpcr(vmi)
    }

    /// Returns a Kernel Processor Control Block (KPRCB) for the specified processor.
    ///
    /// The KPRCB is an opaque, per-processor structure embedded within the
    /// KPCR.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `KiProcessorBlock` symbol, offset by the processor ID.
    pub fn kprcb<'a>(
        vmi: VmiState<'a, Self>,
        vcpu_id: VcpuId,
    ) -> Result<WindowsKernelProcessorBlock<'a, Driver>, VmiError> {
        let number_of_processors = Self::number_of_processors(vmi)? as u64;
        let ki_processor_block = this!(vmi).ki_processor_block.get_or_try_init(|| {
            let KiProcessorBlock = symbol!(vmi, KiProcessorBlock);

            let kernel_image_base = Self::kernel_image_base(vmi)?;

            // Pre-read all KPCR addresses for each processor and cache them.
            let mut blocks = Vec::new();
            for cpu in 0..number_of_processors {
                let offset = cpu * vmi.registers().address_width() as u64;
                let addr = vmi.read_va_native(kernel_image_base + KiProcessorBlock + offset)?;
                blocks.push(addr);
            }

            Ok::<_, VmiError>(blocks)
        })?;

        if vcpu_id.0 as usize >= ki_processor_block.len() {
            return Err(WindowsError::InvalidProcessor(vcpu_id).into());
        }

        let prcb = ki_processor_block[vcpu_id.0 as usize];
        if prcb.is_null() {
            return Err(WindowsError::CorruptedStruct("KiProcessorBlock").into());
        }

        Ok(WindowsKernelProcessorBlock::new(vmi, prcb))
    }

    /// Returns the Kernel Processor Control Block (KPRCB) for the processor
    /// whose register state is currently loaded.
    ///
    /// Unlike [`kprcb`](Self::kprcb), which indexes the `KiProcessorBlock`
    /// array by processor ID, this resolves the PRCB from the current KPCR
    /// (`gs`-relative on AMD64) through `KPCR.Prcb`.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `KPCR.Prcb`.
    pub fn current_kprcb<'a>(
        vmi: VmiState<'a, Self>,
    ) -> Result<WindowsKernelProcessorBlock<'a, Driver>, VmiError> {
        let KPCR = offset!(vmi, _KPCR);

        let kpcr = Self::current_kpcr(vmi);
        if kpcr.is_null() {
            return Err(WindowsError::CorruptedStruct("KPCR").into());
        }

        let prcb = kpcr + KPCR.Prcb.offset();
        Ok(WindowsKernelProcessorBlock::new(vmi, prcb))
    }

    /// Returns information from an exception record at the specified address.
    ///
    /// This method reads and parses an `EXCEPTION_RECORD` structure from
    /// memory, providing detailed information about an exception that has
    /// occurred in the system. The returned [`WindowsExceptionRecord`]
    /// contains data such as the exception code, flags, and related memory
    /// addresses.
    pub fn exception_record(
        vmi: VmiState<Self>,
        address: Va,
    ) -> Result<WindowsExceptionRecord, VmiError> {
        #[repr(C)]
        #[derive(Debug, Copy, Clone, FromBytes, IntoBytes)]
        #[allow(non_camel_case_types, non_snake_case)]
        struct _EXCEPTION_RECORD {
            ExceptionCode: u32,
            ExceptionFlags: u32,
            ExceptionRecord: u64,
            ExceptionAddress: u64,
            NumberParameters: u64,
            ExceptionInformation: [u64; 15],
        }

        let record = vmi.read_struct::<_EXCEPTION_RECORD>(address)?;

        Ok(WindowsExceptionRecord {
            code: record.ExceptionCode,
            flags: record.ExceptionFlags,
            record: record.ExceptionRecord.into(),
            address: record.ExceptionAddress.into(),
            information: record.ExceptionInformation
                [..u64::min(record.NumberParameters, 15) as usize]
                .to_vec(),
        })
    }

    /// Returns the last status value for the current thread.
    ///
    /// In Windows, the last status value is typically used to store error codes
    /// or success indicators from system calls. This method reads this value
    /// from the Thread Environment Block (TEB) of the current thread, providing
    /// insight into the outcome of recent operations performed by the thread.
    ///
    /// Returns `None` if the TEB is not available.
    ///
    /// # Notes
    ///
    /// `LastStatusValue` is a `NTSTATUS` value, whereas `LastError` is a Win32
    /// error code. The two values are related but not identical. You can obtain
    /// the Win32 error code by calling
    /// [`VmiOs::last_error`].
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `NtCurrentTeb()->LastStatusValue`.
    pub fn last_status(vmi: VmiState<Self>) -> Result<Option<u32>, VmiError> {
        let KTHREAD = offset!(vmi, _KTHREAD);
        let TEB = offset!(vmi, _TEB);

        let current_thread = Self::current_thread(vmi)?.object()?;
        let teb = vmi.read_va_native(current_thread.0 + KTHREAD.Teb.offset())?;

        if teb.is_null() {
            return Ok(None);
        }

        let result = vmi.read_u32(teb + TEB.LastStatusValue.offset())?;
        Ok(Some(result))
    }

    /// Returns the idle process (PID 0).
    ///
    /// The idle process is a special system process that runs when no other
    /// threads are ready to execute on a processor.
    ///
    /// # Notes
    ///
    /// This value is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `PsIdleProcess` symbol.
    pub fn idle_process<'a>(
        vmi: VmiState<'a, Self>,
    ) -> Result<WindowsProcess<'a, Driver>, VmiError> {
        let ps_idle_process = this!(vmi)
            .ps_idle_process
            .get_or_try_init(|| {
                let PsIdleProcess = symbol!(vmi, PsIdleProcess);

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                vmi.read_va_native(kernel_image_base + PsIdleProcess)
            })
            .copied()?;

        Ok(WindowsProcess::new(vmi, ProcessObject(ps_idle_process)))
    }

    /// Returns the idle thread for the current processor.
    ///
    /// The idle thread is a per-processor thread that runs when no other
    /// threads are scheduled on that processor.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `KPCR.Prcb.IdleThread`.
    pub fn idle_thread<'a>(vmi: VmiState<'a, Self>) -> Result<WindowsThread<'a, Driver>, VmiError> {
        Self::current_kprcb(vmi)?.idle_thread()
    }

    /// Returns the virtual address of the Page Frame Number (PFN) database.
    ///
    /// The PFN database is a critical data structure in Windows memory management,
    /// containing information about each physical page in the system.
    ///
    /// # Notes
    ///
    /// This value is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `MmPfnDatabase` symbol.
    fn pfn_database(vmi: VmiState<Self>) -> Result<Va, VmiError> {
        this!(vmi)
            .mm_pfn_database
            .get_or_try_init(|| {
                let MmPfnDatabase = symbol!(vmi, MmPfnDatabase);

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                vmi.read_va_native(kernel_image_base + MmPfnDatabase)
            })
            .copied()
    }

    /// Returns the Windows object.
    pub fn object<'a>(
        vmi: VmiState<'a, Self>,
        va: Va,
    ) -> Result<WindowsObject<'a, Driver>, VmiError> {
        Ok(WindowsObject::new(vmi, va))
    }

    /// Returns a Windows object type for the given object kind.
    ///
    /// # Notes
    ///
    /// The object type is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// - `File` corresponds to `IoFileObjectType`.
    /// - `Job` corresponds to `PsJobType`.
    /// - `Key` corresponds to `CmKeyObjectType`.
    /// - `Process` corresponds to `PsProcessType`.
    /// - `Thread` corresponds to `PsThreadType`.
    /// - `Token` corresponds to `SeTokenObjectType`.
    /// - Other types are not supported.
    pub fn object_type<'a>(
        vmi: VmiState<'a, Self>,
        kind: WindowsObjectTypeKind,
    ) -> Result<WindowsObjectType<'a, Driver>, VmiError> {
        if let Some(va) = this!(vmi).object_type_cache.borrow().get(&kind).copied() {
            return Ok(WindowsObjectType::new(vmi, va));
        }

        let symbol = match kind {
            WindowsObjectTypeKind::File => symbol!(vmi, IoFileObjectType),
            WindowsObjectTypeKind::Job => symbol!(vmi, PsJobType),
            WindowsObjectTypeKind::Key => symbol!(vmi, CmKeyObjectType),
            WindowsObjectTypeKind::Process => symbol!(vmi, PsProcessType),
            WindowsObjectTypeKind::Thread => symbol!(vmi, PsThreadType),
            WindowsObjectTypeKind::Token => symbol!(vmi, SeTokenObjectType),
            _ => return Err(VmiError::NotSupported),
        };

        let va = vmi.read_va(Self::kernel_image_base(vmi)? + symbol)?;
        this!(vmi).object_type_cache.borrow_mut().insert(kind, va);

        Ok(WindowsObjectType::new(vmi, va))
    }

    /// Returns the root directory object for the Windows kernel.
    ///
    /// # Notes
    ///
    /// The object root directory is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `ObpRootDirectoryObject` symbol.
    pub fn object_root_directory<'a>(
        vmi: VmiState<'a, Self>,
    ) -> Result<WindowsDirectoryObject<'a, Driver>, VmiError> {
        let object_root_directory = this!(vmi)
            .object_root_directory
            .get_or_try_init(|| {
                let ObpRootDirectoryObject = symbol!(vmi, ObpRootDirectoryObject);

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                vmi.read_va_native(kernel_image_base + ObpRootDirectoryObject)
            })
            .copied()?;

        Ok(WindowsDirectoryObject::new(vmi, object_root_directory))
    }

    /// Returns the object header cookie used for obfuscating object types.
    /// Returns `None` if the cookie is not present in the kernel image.
    ///
    /// # Notes
    ///
    /// Windows 10 introduced a security feature that obfuscates the type
    /// of kernel objects by XORing the `TypeIndex` field in the object header
    /// with a random cookie value. This method fetches that cookie, which is
    /// essential for correctly interpreting object headers in memory.
    ///
    /// The cookie is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `ObHeaderCookie` symbol.
    pub fn object_header_cookie(vmi: VmiState<Self>) -> Result<Option<u8>, VmiError> {
        let ObHeaderCookie = match symbol!(vmi, ObHeaderCookie) {
            Some(cookie) => cookie,
            None => return Ok(None),
        };

        Ok(Some(
            this!(vmi)
                .object_header_cookie
                .get_or_try_init(|| {
                    let kernel_image_base = Self::kernel_image_base(vmi)?;
                    vmi.read_u8(kernel_image_base + ObHeaderCookie)
                })
                .copied()?,
        ))
    }

    /// Returns the Windows object attributes.
    pub fn object_attributes<'a>(
        vmi: VmiState<'a, Self>,
        object_attributes: Va,
    ) -> Result<WindowsObjectAttributes<'a, Driver>, VmiError> {
        Ok(WindowsObjectAttributes::new(vmi, object_attributes))
    }

    /// Resolves an absolute object-namespace path to a named object.
    ///
    /// Descends from the root directory ([`object_root_directory`]) one
    /// component at a time.
    ///
    /// Returns `Ok(None)` when a component does not exist, or when an
    /// intermediate component resolves to something other than a
    /// `Directory`. The final component may be any object type.
    ///
    /// Does not follow `SymbolicLink` objects.
    ///
    /// [`object_root_directory`]: Self::object_root_directory
    pub fn lookup_object<'a>(
        vmi: VmiState<'a, Self>,
        path: impl AsRef<str>,
    ) -> Result<Option<WindowsObject<'a, Driver>>, VmiError> {
        Self::object_root_directory(vmi)?.lookup(path)
    }

    /// Returns an iterator over all loaded registry hives.
    ///
    /// This method returns an iterator over all loaded registry hives. It
    /// reads the `CmpHiveListHead` symbol from the kernel image and iterates
    /// over the linked list of `_CMHIVE` structures representing each hive.
    pub fn hives<'a>(
        vmi: VmiState<'a, Self>,
    ) -> Result<
        impl Iterator<Item = Result<WindowsHive<'a, Driver>, VmiError>> + use<'a, Driver>,
        VmiError,
    > {
        let CmpHiveListHead = Self::kernel_image_base(vmi)? + symbol!(vmi, CmpHiveListHead);
        let CMHIVE = offset!(vmi, _CMHIVE);

        Ok(
            ListEntryIterator::new(vmi, CmpHiveListHead, CMHIVE.HiveList.offset())
                .map(move |result| result.map(|entry| WindowsHive::new(vmi, entry))),
        )
    }

    /// Resolves an absolute registry path against the loaded hive set.
    ///
    /// Picks the hive whose `HiveRootPath` is the longest component-aligned
    /// case-insensitive prefix of `path`, strips that prefix, and forwards
    /// the remainder to [`WindowsHive::lookup`].
    ///
    /// Returns `Ok(None)` when no hive root prefixes the path or when the
    /// descent does not find the key.
    ///
    /// Hives with an empty `HiveRootPath` match any input at depth zero,
    /// so they only win when no loaded hive owns a real prefix.
    ///
    /// Does not follow `HIVE_EXIT` links into other hives.
    pub fn lookup_key<'a>(
        vmi: VmiState<'a, Self>,
        path: impl AsRef<str>,
    ) -> Result<Option<WindowsKeyNode<'a, Driver>>, VmiError> {
        let path = path.as_ref();
        let path_components = path
            .split('\\')
            .filter(|component| !component.is_empty())
            .collect::<Vec<_>>();

        let mut best = None;

        for hive in Self::hives(vmi)? {
            let hive = match hive {
                Ok(hive) => hive,
                Err(err) => {
                    tracing::trace!(%err, "skipping unreadable hive entry");
                    continue;
                }
            };

            let root = match hive.hive_root_path() {
                Ok(root) => root,
                Err(err) => {
                    tracing::trace!(%err, "skipping hive with unreadable HiveRootPath");
                    continue;
                }
            };

            let mut depth = 0;
            let mut matched = true;
            for root_component in root.split('\\').filter(|component| !component.is_empty()) {
                let path_component = match path_components.get(depth) {
                    Some(path_component) => path_component,
                    None => {
                        matched = false;
                        break;
                    }
                };

                if !path_component.eq_ignore_ascii_case(root_component) {
                    matched = false;
                    break;
                }

                depth += 1;
            }

            if !matched {
                continue;
            }

            let beats_best = match &best {
                Some((_, best_depth)) => depth > *best_depth,
                None => true,
            };

            if beats_best {
                best = Some((hive, depth));
            }
        }

        match best {
            Some((hive, depth)) => {
                let rest = path_components[depth..].join("\\");
                hive.lookup(rest)
            }
            None => Ok(None),
        }
    }

    /// Reads an `_EX_FAST_REF` and returns the referenced object's
    /// virtual address, with the low reference-count bits masked off.
    pub fn read_fast_ref(vmi: VmiState<Self>, va: Va) -> Result<Va, VmiError> {
        let EX_FAST_REF = offset!(vmi, _EX_FAST_REF);
        debug_assert_eq!(EX_FAST_REF.RefCnt.offset(), 0);
        debug_assert_eq!(EX_FAST_REF.RefCnt.bit_position(), 0);

        let object = vmi.read_va_native(va)?;

        // For Amd64:
        //   let object = object & !0xf;
        // For x86:
        //   let object = object & !0x7;
        Ok(object & !((1 << EX_FAST_REF.RefCnt.bit_length()) - 1))
    }

    /// Reads string of bytes from an `_ANSI_STRING` structure.
    ///
    /// This method reads a native `_ANSI_STRING` structure which contains
    /// an ASCII/ANSI string. The structure is read according to the current
    /// OS's architecture (32-bit or 64-bit).
    pub fn read_ansi_string_bytes(vmi: VmiState<Self>, va: Va) -> Result<Vec<u8>, VmiError> {
        Self::read_ansi_string_bytes_in(vmi, vmi.access_context(va))
    }

    /// Reads string of bytes from a 32-bit version of `_ANSI_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` structures in
    /// 32-bit processes or WoW64 processes where pointers are 32 bits.
    pub fn read_ansi_string32_bytes(vmi: VmiState<Self>, va: Va) -> Result<Vec<u8>, VmiError> {
        Self::read_ansi_string32_bytes_in(vmi, vmi.access_context(va))
    }

    /// Reads string of bytes from a 64-bit version of `_ANSI_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` structures in
    /// 64-bit processes where pointers are 64 bits.
    pub fn read_ansi_string64_bytes(vmi: VmiState<Self>, va: Va) -> Result<Vec<u8>, VmiError> {
        Self::read_ansi_string64_bytes_in(vmi, vmi.access_context(va))
    }

    /// Reads string from an `_ANSI_STRING` structure.
    ///
    /// This method reads a native `_ANSI_STRING` structure which contains
    /// an ASCII/ANSI string. The structure is read according to the current
    /// OS's architecture (32-bit or 64-bit).
    pub fn read_ansi_string(vmi: VmiState<Self>, va: Va) -> Result<String, VmiError> {
        Self::read_ansi_string_in(vmi, vmi.access_context(va))
    }

    /// Reads string from a 32-bit version of `_ANSI_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` structures in
    /// 32-bit processes or WoW64 processes where pointers are 32 bits.
    pub fn read_ansi_string32(vmi: VmiState<Self>, va: Va) -> Result<String, VmiError> {
        Self::read_ansi_string32_in(vmi, vmi.access_context(va))
    }

    /// Reads string from a 64-bit version of `_ANSI_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` structures in
    /// 64-bit processes where pointers are 64 bits.
    pub fn read_ansi_string64(vmi: VmiState<Self>, va: Va) -> Result<String, VmiError> {
        Self::read_ansi_string64_in(vmi, vmi.access_context(va))
    }

    /// Reads string from a `_UNICODE_STRING` structure.
    ///
    /// This method reads a native `_UNICODE_STRING` structure which contains
    /// a UTF-16 string. The structure is read according to the current OS's
    /// architecture (32-bit or 64-bit).
    pub fn read_unicode_string_bytes(vmi: VmiState<Self>, va: Va) -> Result<Vec<u16>, VmiError> {
        Self::read_unicode_string_bytes_in(vmi, vmi.access_context(va))
    }

    /// Reads string from a 32-bit version of `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_UNICODE_STRING` structures
    /// in 32-bit processes or WoW64 processes where pointers are 32 bits.
    pub fn read_unicode_string32_bytes(vmi: VmiState<Self>, va: Va) -> Result<Vec<u16>, VmiError> {
        Self::read_unicode_string32_bytes_in(vmi, vmi.access_context(va))
    }

    /// Reads string from a 64-bit version of `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_UNICODE_STRING` structures
    /// in 64-bit processes where pointers are 64 bits.
    pub fn read_unicode_string64_bytes(vmi: VmiState<Self>, va: Va) -> Result<Vec<u16>, VmiError> {
        Self::read_unicode_string64_bytes_in(vmi, vmi.access_context(va))
    }

    /// Reads string from a `_UNICODE_STRING` structure.
    ///
    /// This method reads a native `_UNICODE_STRING` structure which contains
    /// a UTF-16 string. The structure is read according to the current OS's
    /// architecture (32-bit or 64-bit).
    pub fn read_unicode_string(vmi: VmiState<Self>, va: Va) -> Result<String, VmiError> {
        Self::read_unicode_string_in(vmi, vmi.access_context(va))
    }

    /// Reads string from a 32-bit version of `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_UNICODE_STRING` structures
    /// in 32-bit processes or WoW64 processes where pointers are 32 bits.
    pub fn read_unicode_string32(vmi: VmiState<Self>, va: Va) -> Result<String, VmiError> {
        Self::read_unicode_string32_in(vmi, vmi.access_context(va))
    }

    /// Reads string from a 64-bit version of `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_UNICODE_STRING` structures
    /// in 64-bit processes where pointers are 64 bits.
    pub fn read_unicode_string64(vmi: VmiState<Self>, va: Va) -> Result<String, VmiError> {
        Self::read_unicode_string64_in(vmi, vmi.access_context(va))
    }

    /// Reads string of bytes from a 32-bit version of `_ANSI_STRING` or
    /// `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` or
    /// `_UNICODE_STRING` structures in 32-bit processes or WoW64 processes
    /// where pointers are 32 bits.
    fn read_string32_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<Vec<u8>, VmiError> {
        let mut ctx = ctx.into();

        let mut buffer = [0u8; 8];
        vmi.read_in(ctx, &mut buffer)?;

        let string_length = u16::from_le_bytes([buffer[0], buffer[1]]);

        if string_length == 0 {
            return Ok(Vec::new());
        }

        // let string_maximum_length = u16::from_le_bytes([buffer[2], buffer[3]]);
        let string_buffer = u32::from_le_bytes([buffer[4], buffer[5], buffer[6], buffer[7]]);

        if string_buffer == 0 {
            tracing::warn!(
                addr = %Hex(ctx.address),
                len = string_length,
                "string buffer is NULL"
            );

            return Ok(Vec::new());
        }

        ctx.address = string_buffer as u64;

        let mut buffer = vec![0u8; string_length as usize];
        vmi.read_in(ctx, &mut buffer)?;

        Ok(buffer)
    }

    /// Reads string of bytes from a 64-bit version of `_ANSI_STRING` or
    /// `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` or
    /// `_UNICODE_STRING` structures in 64-bit processes where pointers
    /// are 64 bits.
    fn read_string64_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<Vec<u8>, VmiError> {
        let mut ctx = ctx.into();

        let mut buffer = [0u8; 16];
        vmi.read_in(ctx, &mut buffer)?;

        let string_length = u16::from_le_bytes([buffer[0], buffer[1]]);

        if string_length == 0 {
            return Ok(Vec::new());
        }

        // We intentionally skip reading the MaximumLength field,
        // since we don't actually need it.
        // let string_maximum_length = u16::from_le_bytes([buffer[2], buffer[3]]);

        #[rustfmt::skip]
        let string_buffer = u64::from_le_bytes([
            buffer[ 8], buffer[ 9], buffer[10], buffer[11],
            buffer[12], buffer[13], buffer[14], buffer[15],
        ]);

        if string_buffer == 0 {
            tracing::warn!(
                addr = %Hex(ctx.address),
                len = string_length,
                "string buffer is NULL"
            );

            return Ok(Vec::new());
        }

        ctx.address = string_buffer;

        let mut buffer = vec![0u8; string_length as usize];
        vmi.read_in(ctx, &mut buffer)?;

        Ok(buffer)
    }

    /// Reads string of bytes from an `_ANSI_STRING` structure.
    ///
    /// This method reads a native `_ANSI_STRING` structure which contains
    /// an ASCII/ANSI string. The structure is read according to the current
    /// OS's architecture (32-bit or 64-bit).
    pub fn read_ansi_string_bytes_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<Vec<u8>, VmiError> {
        match vmi.registers().address_width() {
            4 => Self::read_ansi_string32_bytes_in(vmi, ctx),
            8 => Self::read_ansi_string64_bytes_in(vmi, ctx),
            _ => Err(VmiError::InvalidAddressWidth),
        }
    }

    /// Reads string of bytes from a 32-bit version of `_ANSI_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` structures in
    /// 32-bit processes or WoW64 processes where pointers are 32 bits.
    pub fn read_ansi_string32_bytes_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<Vec<u8>, VmiError> {
        Self::read_string32_in(vmi, ctx)
    }

    /// Reads string of bytes from a 64-bit version of `_ANSI_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` structures in
    /// 64-bit processes where pointers are 64 bits.
    pub fn read_ansi_string64_bytes_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<Vec<u8>, VmiError> {
        Self::read_string64_in(vmi, ctx)
    }

    /// Reads string from an `_ANSI_STRING` structure.
    ///
    /// This method reads a native `_ANSI_STRING` structure which contains
    /// an ASCII/ANSI string. The structure is read according to the current
    /// OS's architecture (32-bit or 64-bit).
    pub fn read_ansi_string_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<String, VmiError> {
        match vmi.registers().address_width() {
            4 => Self::read_ansi_string32_in(vmi, ctx),
            8 => Self::read_ansi_string64_in(vmi, ctx),
            _ => Err(VmiError::InvalidAddressWidth),
        }
    }

    /// Reads string from a 32-bit version of `_ANSI_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` structures in
    /// 32-bit processes or WoW64 processes where pointers are 32 bits.
    pub fn read_ansi_string32_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<String, VmiError> {
        Ok(String::from_utf8_lossy(&Self::read_ansi_string32_bytes_in(vmi, ctx)?).into())
    }

    /// Reads string from a 64-bit version of `_ANSI_STRING` structure.
    ///
    /// This method is specifically for reading `_ANSI_STRING` structures in
    /// 64-bit processes where pointers are 64 bits.
    pub fn read_ansi_string64_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<String, VmiError> {
        Ok(String::from_utf8_lossy(&Self::read_ansi_string64_bytes_in(vmi, ctx)?).into())
    }

    /// Reads string from a `_UNICODE_STRING` structure.
    ///
    /// This method reads a native `_UNICODE_STRING` structure which contains
    /// a UTF-16 string. The structure is read according to the current OS's
    /// architecture (32-bit or 64-bit).
    pub fn read_unicode_string_bytes_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<Vec<u16>, VmiError> {
        match vmi.registers().address_width() {
            4 => Self::read_unicode_string32_bytes_in(vmi, ctx),
            8 => Self::read_unicode_string64_bytes_in(vmi, ctx),
            _ => Err(VmiError::InvalidAddressWidth),
        }
    }

    /// Reads string from a 32-bit version of `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_UNICODE_STRING` structures
    /// in 32-bit processes or WoW64 processes where pointers are 32 bits.
    pub fn read_unicode_string32_bytes_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<Vec<u16>, VmiError> {
        let buffer = Self::read_string32_in(vmi, ctx)?;

        Ok(buffer
            .chunks_exact(2)
            .map(|chunk| u16::from_le_bytes([chunk[0], chunk[1]]))
            .collect::<Vec<_>>())
    }

    /// Reads string from a 64-bit version of `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_UNICODE_STRING` structures
    /// in 64-bit processes where pointers are 64 bits.
    pub fn read_unicode_string64_bytes_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<Vec<u16>, VmiError> {
        let buffer = Self::read_string64_in(vmi, ctx)?;

        Ok(buffer
            .chunks_exact(2)
            .map(|chunk| u16::from_le_bytes([chunk[0], chunk[1]]))
            .collect::<Vec<_>>())
    }

    /// Reads string from a `_UNICODE_STRING` structure.
    ///
    /// This method reads a native `_UNICODE_STRING` structure which contains
    /// a UTF-16 string. The structure is read according to the current OS's
    /// architecture (32-bit or 64-bit).
    pub fn read_unicode_string_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<String, VmiError> {
        match vmi.registers().address_width() {
            4 => Self::read_unicode_string32_in(vmi, ctx),
            8 => Self::read_unicode_string64_in(vmi, ctx),
            _ => Err(VmiError::InvalidAddressWidth),
        }
    }

    /// Reads string from a 32-bit version of `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_UNICODE_STRING` structures
    /// in 32-bit processes or WoW64 processes where pointers are 32 bits.
    pub fn read_unicode_string32_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<String, VmiError> {
        Ok(String::from_utf16_lossy(
            &Self::read_unicode_string32_bytes_in(vmi, ctx)?,
        ))
    }

    /// Reads string from a 64-bit version of `_UNICODE_STRING` structure.
    ///
    /// This method is specifically for reading `_UNICODE_STRING` structures
    /// in 64-bit processes where pointers are 64 bits.
    pub fn read_unicode_string64_in(
        vmi: VmiState<Self>,
        ctx: impl Into<AccessContext>,
    ) -> Result<String, VmiError> {
        Ok(String::from_utf16_lossy(
            &Self::read_unicode_string64_bytes_in(vmi, ctx)?,
        ))
    }

    /// Returns an iterator over a doubly-linked list of `LIST_ENTRY` structures.
    ///
    /// This method is used to iterate over a doubly-linked list of `LIST_ENTRY`
    /// structures in memory. It returns an iterator that yields the virtual
    /// addresses of each `LIST_ENTRY` structure in the list.
    pub fn linked_list<'a>(
        vmi: VmiState<'a, Self>,
        list_head: Va,
        offset: u64,
    ) -> Result<impl Iterator<Item = Result<Va, VmiError>> + use<'a, Driver>, VmiError> {
        Ok(ListEntryIterator::new(vmi, list_head, offset))
    }

    ///////////////////////////////////////////////////////////////////////////
    // VmiRead + VmiWrite
    ///////////////////////////////////////////////////////////////////////////

    fn modify_pfn_reference_count(
        vmi: VmiState<Self>,
        pfn: Gfn,
        increment: i16,
    ) -> Result<Option<u16>, VmiError>
    where
        Driver: VmiWrite,
    {
        let MMPFN = offset!(vmi, _MMPFN);

        // const ZeroedPageList: u16 = 0;
        // const FreePageList: u16 = 1;
        const StandbyPageList: u16 = 2; //this list and before make up available pages.
        const ModifiedPageList: u16 = 3;
        const ModifiedNoWritePageList: u16 = 4;
        // const BadPageList: u16 = 5;
        const ActiveAndValid: u16 = 6;
        // const TransitionPage: u16 = 7;

        let pfn = Self::pfn_database(vmi)? + u64::from(pfn) * MMPFN.len() as u64;

        //
        // In the _MMPFN structure, the fields are like this:
        //
        // ```c
        // struct _MMPFN {
        //     ...
        //     union {
        //         USHORT ReferenceCount;
        //         struct {
        //             UCHAR PageLocation : 3;
        //             ...
        //         } e1;
        //         ...
        //     } u3;
        // };
        // ```
        //
        // On the systems tested (Win7 - Win11), the `PageLocation` is right
        // after `ReferenceCount`. We can read the value of both fields at once.
        //

        debug_assert_eq!(MMPFN.ReferenceCount.size(), 2);
        debug_assert_eq!(
            MMPFN.ReferenceCount.offset() + MMPFN.ReferenceCount.size(),
            MMPFN.PageLocation.offset()
        );
        debug_assert_eq!(MMPFN.PageLocation.bit_position(), 0);
        debug_assert_eq!(MMPFN.PageLocation.bit_length(), 3);

        let pfn_value = vmi.read_u32(pfn + MMPFN.ReferenceCount.offset())?;
        let flags = (pfn_value >> 16) as u16;
        let ref_count = (pfn_value & 0xFFFF) as u16;

        let page_location = flags & 7;

        tracing::debug!(
            %pfn,
            ref_count,
            flags = %Hex(flags),
            page_location,
            increment,
            "modifying PFN reference count"
        );

        //
        // Make sure the page is good (when coming from hibernate/standby pages
        // can be in modified state).
        //

        if !matches!(
            page_location,
            StandbyPageList | ModifiedPageList | ModifiedNoWritePageList | ActiveAndValid
        ) {
            tracing::warn!(
                %pfn,
                ref_count,
                flags = %Hex(flags),
                page_location,
                increment,
                "page is not active and valid"
            );
            return Ok(None);
        }

        if ref_count == 0 {
            tracing::warn!(
                %pfn,
                ref_count,
                flags = %Hex(flags),
                page_location,
                increment,
                "page is not initialized"
            );
            return Ok(None);
        }

        let new_ref_count = match ref_count.checked_add_signed(increment) {
            Some(new_ref_count) => new_ref_count,
            None => {
                tracing::warn!(
                    %pfn,
                    ref_count,
                    flags = %Hex(flags),
                    page_location,
                    increment,
                    "page is at maximum reference count"
                );
                return Ok(None);
            }
        };

        vmi.write_u16(pfn + MMPFN.ReferenceCount.offset(), new_ref_count)?;

        Ok(Some(new_ref_count))
    }

    /// Increments the reference count of a Page Frame Number (PFN).
    pub fn lock_pfn(vmi: VmiState<Self>, pfn: Gfn) -> Result<Option<u16>, VmiError>
    where
        Driver: VmiWrite,
    {
        Self::modify_pfn_reference_count(vmi, pfn, 1)
    }

    /// Decrements the reference count of a Page Frame Number (PFN).
    pub fn unlock_pfn(vmi: VmiState<Self>, pfn: Gfn) -> Result<Option<u16>, VmiError>
    where
        Driver: VmiWrite,
    {
        Self::modify_pfn_reference_count(vmi, pfn, -1)
    }
}

#[expect(non_snake_case)]
impl<Driver> VmiOs for WindowsOs<Driver>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    type Architecture = Driver::Architecture;
    type Driver = Driver;

    type Process<'a> = WindowsProcess<'a, Driver>;
    type Thread<'a> = WindowsThread<'a, Driver>;
    type Image<'a> = WindowsImage<'a, Driver>;
    type Module<'a> = WindowsModule<'a, Driver>;
    type UserModule<'a> = WindowsUserModule<'a, Driver>;
    type Region<'a> = WindowsRegion<'a, Driver>;
    type Mapped<'a> = WindowsControlArea<'a, Driver>;

    fn kernel_image_base(vmi: VmiState<Self>) -> Result<Va, VmiError> {
        Driver::Architecture::kernel_image_base(vmi)
    }

    fn kernel_information_string(vmi: VmiState<Self>) -> Result<String, VmiError> {
        this!(vmi)
            .nt_build_lab
            .get_or_try_init(|| {
                let NtBuildLab = symbol!(vmi, NtBuildLab);

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                vmi.read_string(kernel_image_base + NtBuildLab)
            })
            .cloned()
    }

    /// Checks if Kernel Virtual Address Shadow (KVA Shadow) is enabled.
    ///
    /// KVA Shadow is a security feature introduced in Windows 10 that
    /// mitigates Meltdown and Spectre vulnerabilities by isolating
    /// kernel memory from user-mode processes.
    ///
    /// # Notes
    ///
    /// This value is cached after the first read.
    ///
    /// # Implementation Details
    ///
    /// Corresponds to `KiKvaShadow` symbol.
    fn kpti_enabled(vmi: VmiState<Self>) -> Result<bool, VmiError> {
        this!(vmi)
            .ki_kva_shadow
            .get_or_try_init(|| {
                let KiKvaShadow = symbol!(vmi, KiKvaShadow);

                let KiKvaShadow = match KiKvaShadow {
                    Some(KiKvaShadow) => KiKvaShadow,
                    None => return Ok(false),
                };

                let kernel_image_base = Self::kernel_image_base(vmi)?;
                Ok(vmi.read_u8(kernel_image_base + KiKvaShadow)? != 0)
            })
            .copied()
    }

    /// Returns an iterator over all loaded Windows Driver modules.
    ///
    /// This method returns an iterator over all loaded Windows Driver modules.
    /// It reads the `PsLoadedModuleList` symbol from the kernel image and
    /// iterates over the linked list of `KLDR_DATA_TABLE_ENTRY` structures
    /// representing each loaded module.
    fn modules<'a>(
        vmi: VmiState<'a, Self>,
    ) -> Result<impl Iterator<Item = Result<Self::Module<'a>, VmiError>> + use<'a, Driver>, VmiError>
    {
        let PsLoadedModuleList = Self::kernel_image_base(vmi)? + symbol!(vmi, PsLoadedModuleList);
        let KLDR_DATA_TABLE_ENTRY = offset!(vmi, _KLDR_DATA_TABLE_ENTRY);

        Ok(ListEntryIterator::new(
            vmi,
            PsLoadedModuleList,
            KLDR_DATA_TABLE_ENTRY.InLoadOrderLinks.offset(),
        )
        .map(move |result| result.map(|entry| WindowsModule::new(vmi, entry))))
    }

    /// Returns an iterator over all Windows processes.
    ///
    /// This method returns an iterator over all Windows processes. It reads the
    /// `PsActiveProcessHead` symbol from the kernel image and iterates over the
    /// linked list of `EPROCESS` structures representing each process.
    fn processes<'a>(
        vmi: VmiState<'a, Self>,
    ) -> Result<impl Iterator<Item = Result<Self::Process<'a>, VmiError>> + use<'a, Driver>, VmiError>
    {
        let PsActiveProcessHead = Self::kernel_image_base(vmi)? + symbol!(vmi, PsActiveProcessHead);
        let EPROCESS = offset!(vmi, _EPROCESS);

        Ok(ListEntryIterator::new(
            vmi,
            PsActiveProcessHead,
            EPROCESS.ActiveProcessLinks.offset(),
        )
        .map(move |result| result.map(|entry| WindowsProcess::new(vmi, ProcessObject(entry)))))
    }

    fn process(
        vmi: VmiState<'_, Self>,
        process: ProcessObject,
    ) -> Result<Self::Process<'_>, VmiError> {
        Ok(WindowsProcess::new(vmi, process))
    }

    /// Returns the current process.
    fn current_process(vmi: VmiState<'_, Self>) -> Result<Self::Process<'_>, VmiError> {
        Self::current_thread(vmi)?.current_process()
    }

    /// Returns the system process.
    ///
    /// The system process is the first process created by the Windows kernel
    /// during system initialization. It is the parent process of all other
    /// processes in the system.
    fn system_process(vmi: VmiState<'_, Self>) -> Result<Self::Process<'_>, VmiError> {
        let PsInitialSystemProcess =
            Self::kernel_image_base(vmi)? + symbol!(vmi, PsInitialSystemProcess);

        let process = vmi.read_va_native(PsInitialSystemProcess)?;
        Ok(WindowsProcess::new(vmi, ProcessObject(process)))
    }

    fn thread(vmi: VmiState<'_, Self>, thread: ThreadObject) -> Result<Self::Thread<'_>, VmiError> {
        Ok(WindowsThread::new(vmi, thread))
    }

    /// Returns the current thread.
    fn current_thread(vmi: VmiState<'_, Self>) -> Result<Self::Thread<'_>, VmiError> {
        Self::current_kprcb(vmi)?.current_thread()
    }

    fn image(vmi: VmiState<'_, Self>, image_base: Va) -> Result<Self::Image<'_>, VmiError> {
        Ok(WindowsImage::new(vmi, image_base))
    }

    fn module(vmi: VmiState<'_, Self>, module: Va) -> Result<Self::Module<'_>, VmiError> {
        Ok(WindowsModule::new(vmi, module))
    }

    fn user_module(
        vmi: VmiState<'_, Self>,
        module: Va,
        root: Pa,
    ) -> Result<Self::UserModule<'_>, VmiError> {
        Ok(WindowsUserModule::new(vmi, module, root))
    }

    fn region(vmi: VmiState<'_, Self>, region: Va) -> Result<Self::Region<'_>, VmiError> {
        Ok(WindowsRegion::new(vmi, region))
    }

    fn syscall_argument(vmi: VmiState<Self>, index: u64) -> Result<u64, VmiError> {
        Driver::Architecture::syscall_argument(vmi, index)
    }

    fn function_argument(vmi: VmiState<Self>, index: u64) -> Result<u64, VmiError> {
        Driver::Architecture::function_argument(vmi, index)
    }

    fn function_return_value(vmi: VmiState<Self>) -> Result<u64, VmiError> {
        Driver::Architecture::function_return_value(vmi)
    }

    fn last_error(vmi: VmiState<Self>) -> Result<Option<u32>, VmiError> {
        let KTHREAD = offset!(vmi, _KTHREAD);
        let TEB = offset!(vmi, _TEB);

        let current_thread = Self::current_thread(vmi)?.object()?;
        let teb = vmi.read_va_native(current_thread.0 + KTHREAD.Teb.offset())?;

        if teb.is_null() {
            return Ok(None);
        }

        let result = vmi.read_u32(teb + TEB.LastErrorValue.offset())?;

        Ok(Some(result))
    }
}