struct vm_map_links {
    struct vm_map_entry     *prev;          /* 指向前一个虚拟内存映射条目 */
    struct vm_map_entry     *next;          /* 指向下一个虚拟内存映射条目 */
    vm_map_offset_t         start;          /* 当前映射的起始地址 */
    vm_map_offset_t         end;            /* 当前映射的结束地址 */
};

struct vm_map_header {
    struct vm_map_links     links;          /* 虚拟内存映射条目的链表头，包含第一个、最后一个、最小与最大地址 */
    int                     nentries;       /* 当前映射中的条目数量 */
    uint16_t                page_shift;     /* 页面大小的位移量（用于计算页面大小） */
    uint16_t                entries_pageable : 1;   /* 标志位，表示映射条目是否可分页 */
    uint16_t                __padding : 15; /* 填充位，确保结构体对齐 */
#ifdef VM_MAP_STORE_USE_RB
    struct rb_head          rb_head_store;  /* 红黑树的头，用于存储映射条目（如果启用了红黑树存储） */
#endif /* VM_MAP_STORE_USE_RB */
};

struct _vm_map {
    lck_rw_t                lock;           /* 读写锁，用于保护映射的并发访问 */
    struct vm_map_header    hdr;            /* 映射条目的头部信息 */
#define min_offset              hdr.links.start /* 映射范围的最小地址 */
#define max_offset              hdr.links.end   /* 映射范围的最大地址 */
    pmap_t                  XNU_PTRAUTH_SIGNED_PTR("_vm_map.pmap") pmap;           /* 物理内存映射 */
    vm_map_size_t           size;           /* 虚拟内存映射的总大小 */
    uint64_t                size_limit;     /* 地址空间大小的限制 */
    uint64_t                data_limit;     /* 数据大小的限制 */
    vm_map_size_t           user_wire_limit;/* 用户锁定内存的限制，wire即为不能分页换出 */
    vm_map_size_t           user_wire_size; /* 当前用户锁定内存的大小 */
#if __x86_64__
    vm_map_offset_t         vmmap_high_start; /* 高地址空间的起始地址（仅用于 x86_64 架构） */
#endif /* __x86_64__ */

    os_ref_atomic_t         map_refcnt;       /* 引用计数，用于管理映射的生命周期 */

#if CONFIG_MAP_RANGES
#define VM_MAP_EXTRA_RANGES_MAX 1024
    struct mach_vm_range    default_range;  /* 默认的虚拟内存范围 */
    struct mach_vm_range    data_range;     /* 数据段的虚拟内存范围 */

    uint16_t                extra_ranges_count; /* 额外的虚拟内存范围数量 */
    vm_map_user_range_t     extra_ranges;   /* 额外的虚拟内存范围 */
#endif /* CONFIG_MAP_RANGES */

    union {
        vm_map_offset_t         vmu1_highest_entry_end; /* 最高分配的映射条目的结束地址 */
        vm_map_offset_t         vmu1_lowest_unnestable_start; /* 嵌套映射中最低不可解嵌套的起始地址 */
    } vmu1;
#define highest_entry_end       vmu1.vmu1_highest_entry_end
#define lowest_unnestable_start vmu1.vmu1_lowest_unnestable_start
    vm_map_entry_t          hint;           /* 用于快速查找的提示，去查找可用的一片虚拟地址空间 */
    union {
        struct vm_map_links* vmmap_hole_hint;   /* 用于快速查找空闲区域的提示 */
        struct vm_map_corpse_footprint_header *vmmap_corpse_footprint; /* 用于诊断的 corpse 内存映射 */
    } vmmap_u_1;
#define hole_hint vmmap_u_1.vmmap_hole_hint
#define vmmap_corpse_footprint vmmap_u_1.vmmap_corpse_footprint
    union {
        vm_map_entry_t          _first_free;    /* 第一个空闲空间的提示 */
        struct vm_map_links*    _holes;         /* 所有空闲区域的链表 */
    } f_s;                                          /* 空闲空间数据结构的联合体 */

#define first_free              f_s._first_free
#define holes_list              f_s._holes

    unsigned int
    /* boolean_t */ wait_for_space:1,         /* 调用者是否应该等待空间 */
    /* boolean_t */ wiring_required:1,        /* 所有内存是否需要被锁定 */
    /* boolean_t */ no_zero_fill:1,           /* 是否禁止零填充缺失的页面 */
    /* boolean_t */ mapped_in_other_pmaps:1,  /* 该子映射是否被映射到使用不同物理映射的映射中 */
    /* boolean_t */ switch_protect:1,         /* 在切换时保护映射免受写错误 */
    /* boolean_t */ disable_vmentry_reuse:1,  /* 是否禁止重用虚拟内存条目 */
    /* boolean_t */ map_disallow_data_exec:1, /* 是否禁止从数据页面执行代码 */
    /* boolean_t */ holelistenabled:1,
    /* boolean_t */ is_nested_map:1,
    /* boolean_t */ map_disallow_new_exec:1,  /* 是否禁止新的可执行代码 */
    /* boolean_t */ jit_entry_exists:1,
    /* boolean_t */ has_corpse_footprint:1,
    /* boolean_t */ terminated:1,
    /* boolean_t */ is_alien:1,               /* 用于平台模拟，例如在 macOS 上模拟 iOS */
    /* boolean_t */ cs_enforcement:1,         /* 代码签名强制执行 */
    /* boolean_t */ cs_debugged:1,            /* 代码签名但允许调试 */
    /* boolean_t */ reserved_regions:1,       /* 是否有保留区域 */
    /* boolean_t */ single_jit:1,             /* 是否只允许一个 JIT 映射 */
    /* boolean_t */ never_faults:1,           /* 该映射是否永远不会引发错误 */
    /* boolean_t */ uses_user_ranges:1,       /* 是否使用用户虚拟内存范围 */
    /* boolean_t */ tpro_enforcement:1,       /* 是否强制执行 TPRO 传播 */
    /* boolean_t */ corpse_source:1,          /* 该映射是否用于创建诊断用的 corpse */
    /* reserved */ res0:1,
    /* reserved  */pad:9;
    unsigned int            timestamp;        /* 版本号，用于检测映射的更改 */
};

struct pmap {
    tt_entry_t *tte;  /* 指向根页表（Translation Table Entry）的指针 */
    pmap_paddr_t ttep;  /* 根页表的物理地址 */

    vm_map_address_t min;  /* 最低可寻址的虚拟地址（包含） */
    vm_map_address_t max;  /* 最高可寻址的虚拟地址（不包含） */

#if ARM_PARAMETERIZED_PMAP
    const struct page_table_attr * pmap_pt_attr;  /* 页表布局的详细信息 */
#endif /* ARM_PARAMETERIZED_PMAP */

    ledger_t ledger;  /* 用于跟踪物理内存映射的分类账 */

    decl_lck_rw_data(, rwlock);  /* 读写锁，用于保护 pmap 的并发访问 */

    queue_chain_t pmaps;  /* 全局 pmap 链表 */

    tt_entry_t *tt_entry_free;  /* 空闲的页表条目链表 */

    struct pmap      *nested_pmap;  /* 指向嵌套（共享）区域的 pmap */
    vm_map_address_t nested_region_addr;  /* 嵌套区域的起始地址 */
    vm_map_offset_t  nested_region_size;  /* 嵌套区域的大小 */
    vm_map_offset_t  nested_region_true_start;  /* 嵌套区域的真实起始地址 */
    vm_map_offset_t  nested_region_true_end;  /* 嵌套区域的真实结束地址 */
    bitmap_t         *nested_region_unnested_table_bitmap;  /* 嵌套区域的未嵌套表位图 */

    _Atomic int32_t ref_count;  /* pmap 的引用计数 */

    uint32_t nested_no_bounds_refcnt;  /* 未设置边界的嵌套 pmap 的数量 */

    uint16_t asid;  /* 地址空间标识符（ASID）或虚拟机标识符（VMID），0为内核保留 */

#if MACH_ASSERT
    int pmap_pid;  /* 进程 ID（仅在调试模式下使用） */
    char pmap_procname[17];  /* 进程名称（仅在调试模式下使用） */
#endif /* MACH_ASSERT */

    bool reserved0;  /* 保留字段 */

    bool pmap_vm_map_cs_enforced;  /* 是否启用了代码签名强制 */

    bool reserved1;  /* 保留字段 */
    unsigned int reserved2;  /* 保留字段 */
    unsigned int reserved3;  /* 保留字段 */

#if defined(CONFIG_ROSETTA)
    bool is_rosetta;  /* 是否用于 Rosetta 模拟 */
#else
    bool reserved4;  /* 保留字段 */
#endif /* defined(CONFIG_ROSETTA) */

#if DEVELOPMENT || DEBUG
    bool footprint_suspended;  /* 是否暂停了内存占用跟踪 */
    bool footprint_was_suspended;  /* 内存占用跟踪是否曾经被暂停 */
#endif /* DEVELOPMENT || DEBUG */

    bool nx_enabled;  /* 是否启用了不可执行（NX）功能 */

    bool is_64bit;  /* 是否表示 64 位地址空间 */

    bool nested_has_no_bounds_ref;  /* 是否在没有设置边界的情况下嵌套了 pmap */

    bool nested_bounds_set;  /* 嵌套边界是否已设置 */

#if HAS_APPLE_PAC
    bool disable_jop;  /* 是否禁用了跳转导向编程（JOP）保护 */
#else
    bool reserved5;  /* 保留字段 */
#endif /* HAS_APPLE_PAC */

    bool reserved6;  /* 保留字段 */

#define PMAP_TYPE_USER 0 /* ordinary pmap */
#define PMAP_TYPE_KERNEL 1 /* kernel pmap */
#define PMAP_TYPE_COMMPAGE 2 /* commpage pmap */
#define PMAP_TYPE_NESTED 3 /* pmap nested within another pmap */
    uint8_t type;  /* pmap 类型（用户、内核、commpage 或嵌套） */

    decl_lck_rw_data(, txm_lck);  /* 用于保护 TrustedExecutionMonitor 地址空间的读写锁 */
    TXMAddressSpace_t *XNU_PTRAUTH_SIGNED_PTR("pmap.txm_addr_space") txm_addr_space;  /* TrustedExecutionMonitor 地址空间 */
    CSTrust_t txm_trust_level;  /* TrustedExecutionMonitor 的信任级别 */
};

struct vm_map_entry {
    /* 链接到其他条目 */
    struct vm_map_links     links;
#define vme_prev                links.prev  /* 前一个条目 */
#define vme_next                links.next  /* 下一个条目 */
#define vme_start               links.start /* 条目的起始地址 */
#define vme_end                 links.end   /* 条目的结束地址 */

    struct vm_map_store     store; /* 存储一些额外信息，用于快速查改操作，如存储红黑树节点 */

    /* 联合体：用于表示不同的上下文或对象类型，最重要的域，指向是最终对象还是子映射 */
    union {
        vm_offset_t     vme_object_value;  /* 对象的值 */
        struct {
            vm_offset_t vme_atomic:1;      /* 条目不能被拆分或合并 */
            vm_offset_t is_sub_map:1;      /* 对象是否为子映射（submap） */
            vm_offset_t vme_submap:VME_SUBMAP_BITS;  /* 子映射的位字段 */
        };
        struct {
            uint32_t    vme_ctx_atomic : 1;      /* 上下文相关的原子性标志 */
            uint32_t    vme_ctx_is_sub_map : 1;  /* 上下文是否为子映射 */
            uint32_t    vme_context : 30;        /* 上下文信息 */

            /* 联合体：对象或偏移量，或标签的回溯引用 */
            union {
                vm_page_object_t vme_object_or_delta;  /* 对象或偏移量 */
                btref_t vme_tag_btref;                /* 标签的回溯引用 */
            };
        };
    };

    /* 位字段：条目的 VM 标签 */
    unsigned long long
    /* vm_tag_t          */ vme_alias:VME_ALIAS_BITS,   /* 条目的 VM 标签 */
    /* vm_object_offset_t*/ vme_offset:VME_OFFSET_BITS, /* 对象内的偏移量 */

    /* 区域是否共享 */
    /* boolean_t         */ is_shared:1,                /* 区域是否共享 */
    /* 未使用的位 */
    /* boolean_t         */ __unused1:1,
    /* 条目是否正在被修改 */
    /* boolean_t         */ in_transition:1,            /* 条目是否正在被修改 */
    /* 是否有等待者 */
    /* boolean_t         */ needs_wakeup:1,             /* 是否有等待者 */
    /* 用户分页行为提示 */
    /* vm_behavior_t     */ behavior:2,                 /* 用户分页行为提示 */
    /* 对象是否需要复制 */
    /* boolean_t         */ needs_copy:1,               /* 对象是否需要复制 */

    /* 保护属性 */
#if defined(__arm64e__)
    /* vm_prot_t-like    */ protection:3,               /* 保护代码 */
    /* 是否用于可信路径 */
    /* boolean_t         */ used_for_tpro:1,
#else /* __arm64e__ */
    /* vm_prot_t-like    */ protection:4,                /* 保护代码，bit3=UEXEC */
#endif /* __arm64e__ */

    /* 最大保护属性 */
    /* vm_prot_t-like    */ max_protection:4,           /* 最大保护，bit3=UEXEC */
    /* 继承属性 */
    /* vm_inherit_t      */ inheritance:2,              /* 继承属性 */

    /* 是否使用嵌套的 pmap */
    /* boolean_t         */ use_pmap:1,
    /* 新页面是否缓存 */
    /* boolean_t         */ no_cache:1,                 /* 新页面是否缓存 */
    /* 映射是否不可移除 */
    /* boolean_t         */ vme_permanent:1,            /* 映射是否不可移除 */
    /* 是否使用超级页 */
    /* boolean_t         */ superpage_size:1,           /* 是否使用超级页 */
    /* 是否对齐到页大小 */
    /* boolean_t         */ map_aligned:1,              /* 是否对齐到页大小 */
    /* 是否清零固定页面 */
    /* boolean_t         */ zero_wired_pages:1,         /* 是否清零固定页面 */
    /* 是否用于 JIT */
    /* boolean_t         */ used_for_jit:1,             /* 是否用于 JIT */
    /* 是否与代码签名监控关联 */
    /* boolean_t         */ csm_associated:1,           /* 是否与代码签名监控关联 */
    /* 是否使用虚拟大小 */
    /* boolean_t         */ iokit_acct:1,               /* 是否使用虚拟大小 */
    /* 是否启用弹性代码签名 */
    /* boolean_t         */ vme_resilient_codesign:1,   /* 是否启用弹性代码签名 */
    /* 是否启用弹性媒体 */
    /* boolean_t         */ vme_resilient_media:1,      /* 是否启用弹性媒体 */
    /* 是否用于用户调试 */
    /* boolean_t         */ vme_xnu_user_debug:1,       /* 是否用于用户调试 */
    /* 是否禁用读时复制 */
    /* boolean_t         */ vme_no_copy_on_read:1,      /* 是否禁用读时复制 */
    /* 是否允许执行 */
    /* boolean_t         */ translated_allow_execute:1, /* 是否允许执行 */
    /* 对象是否为内核对象 */
    /* boolean_t         */ vme_kernel_object:1;        /* 对象是否为内核对象 */

    /* 固定页面的计数 */
    unsigned short          wired_count;                /* 可以分页如果 = 0 */
    /* 用户固定页面的计数 */
    unsigned short          user_wired_count;           /* 用于 vm_wire */

    /* 调试相关字段 */
#if     DEBUG
#define MAP_ENTRY_CREATION_DEBUG (1)
#define MAP_ENTRY_INSERTION_DEBUG (1)
#endif /* DEBUG */
#if     MAP_ENTRY_CREATION_DEBUG
    struct vm_map_header    *vme_creation_maphdr;       /* 创建时的映射头 */
    uint32_t                vme_creation_bt;            /* 创建时的回溯引用 */
#endif /* MAP_ENTRY_CREATION_DEBUG */
#if     MAP_ENTRY_INSERTION_DEBUG
    uint32_t                vme_insertion_bt;           /* 插入时的回溯引用 */
    vm_map_offset_t         vme_start_original;         /* 原始的起始地址 */
    vm_map_offset_t         vme_end_original;           /* 原始的结束地址 */
#endif /* MAP_ENTRY_INSERTION_DEBUG */
};

struct vm_object {
    /*
     * 在 64 位系统上，我们将挂载在 memq 上的指针打包。
     * 这些指针必须能够指向 memq。
     * 打包的指针需要对齐到 64 字节边界，
     * 这意味着对于 vm_object 来说有两点：
     * (1) memq 结构体必须是结构体的第一个元素，以便我们可以控制其对齐；
     * (2) vm_object 必须对齐到 64 字节边界。
     * 对于静态的 vm_object，这是通过 'aligned' 属性实现的；
     * 对于在 zone pool 中的 vm_object，这是通过将 vm_object 的大小舍入到最近的 64 字节大小来实现的。
     */
    vm_page_queue_head_t    memq;           /* 常驻内存队列 - 必须是第一个元素，因为涉及压缩指针等，里面是vm_page链表 */
    lck_rw_t                Lock;           /* 同步锁 */

    union {
        vm_object_size_t  vou_size;         /* 对象大小（仅在内部对象时有效） */
        int               vou_cache_pages_to_scan; /* 外部对象中尚未访问的页面数 */
    } vo_un1;

    struct vm_page          *memq_hint;     /* 内存队列的提示指针 */
    int                     ref_count;      /* 引用计数 */
    unsigned int            resident_page_count; /* 常驻页面数 */
    unsigned int            wired_page_count;    /* 固定页面数 */
    unsigned int            reusable_page_count; /* 可重用页面数 */

    struct vm_object        *vo_copy;       /* 接收更改页面的副本对象 */
    uint32_t                vo_copy_version; /* 副本版本号 */
    uint32_t                __vo_unused_padding; /* 未使用的填充 */
    struct vm_object        *shadow;        /* 影子对象 */
    memory_object_t         pager;          /* 数据来源的分页器 */

    union {
        vm_object_offset_t vou_shadow_offset; /* 影子对象中的偏移量 */
        clock_sec_t        vou_cache_ts;      /* 外部对象在缓存中的时间戳 */
        task_t             vou_owner;         /* 如果对象是可清除的或有 "ledger_tag"，这是拥有它的任务 */
    } vo_un2;

    vm_object_offset_t      paging_offset;  /* 内存对象中的偏移量 */
    memory_object_control_t pager_control;  /* 数据返回的位置 */

    memory_object_copy_strategy_t copy_strategy; /* 数据复制策略，包括：
    MEMORY_OBJECT_COPY_SYMMETRIC：对称复制策略，多个 CoW 映射共享同一个 vm_object，直到发生写操作时，脏页会被复制到一个新的影子对象（shadow 字段指向原始对象）。
MEMORY_OBJECT_COPY_DELAY：延迟复制策略（非对称复制），vm_object 只保存部分数据，其余数据保存在另一个 vm_object 中（通过 copy 字段指向源对象），发生写操作时，副本对象会接收更改的页面，源对象保持不变。
MEMORY_OBJECT_COPY_NONE：无复制策略，需要逐页复制，速度较慢。
*/

    /*
     * 某些用户进程（主要是虚拟机软件）会获取大量 UPL（通过 IOMemoryDescriptors）
     * 来固定大型 VM 对象中的页面，并溢出 16 位的 "activity_in_progress" 计数器。
     * 由于我们从未强制执行任何限制，因此为了向后兼容，我们将其扩展到 32 位。
     */
    unsigned short          paging_in_progress:16; /* 分页进行中 */
    unsigned short          vo_size_delta;         /* 对象大小的增量 */
    unsigned int            activity_in_progress;  /* 活动进行中 */

    /* 位字段：表示对象的各种状态和行为 */
    unsigned int
    /* boolean_t array */ all_wanted:6,     /* 需要被唤醒的位数组 */
    /* boolean_t */ pager_created:1,        /* 分页器是否已创建 */
    /* boolean_t */ pager_initialized:1,    /* 分页器字段是否已初始化 */
    /* boolean_t */ pager_ready:1,          /* 分页器是否准备好接受请求 */
    /* boolean_t */ pager_trusted:1,        /* 分页器是否可信 */
    /* boolean_t */ can_persist:1,          /* 内核是否可以在所有地址映射引用解除分配后保留数据 */
    /* boolean_t */ internal:1,             /* 是否由内核创建 */
    /* boolean_t */ private:1,              /* 是否是私有对象 */
    /* boolean_t */ pageout:1,              /* 是否是页面换出对象 */
    /* boolean_t */ alive:1,                /* 是否尚未终止 */
    /* boolean_t */ purgable:2,             /* 可清除状态 */
    /* boolean_t */ purgeable_only_by_kernel:1, /* 是否只能由内核清除 */
    /* boolean_t */ purgeable_when_ripe:1,  /* 是否在令牌成熟时清除 */
    /* boolean_t */ shadowed:1,             /* 是否存在影子对象 */
    /* boolean_t */ true_share:1,           /* 是否被多个地方映射 */
    /* boolean_t */ terminating:1,          /* 是否正在终止 */
    /* boolean_t */ named:1,                /* 是否具有内部命名约定 */
    /* boolean_t */ shadow_severed:1,       /* 影子对象是否被切断 */
    /* boolean_t */ phys_contiguous:1,      /* 内存是否物理连续 */
    /* boolean_t */ nophyscache:1,          /* 是否不允许主缓存 */
    /* boolean_t */ for_realtime:1,         /* 是否用于实时代码路径 */
    /* vm_object_destroy_reason_t */ no_pager_reason:2, /* 无分页器的原因 */
#if FBDP_DEBUG_OBJECT_NO_PAGER
    /* boolean_t */ fbdp_tracked:1,         /* 是否被 FBDP 跟踪 */
    __object1_unused_bits:2;
#else /* FBDP_DEBUG_OBJECT_NO_PAGER */
    __object1_unused_bits:3;
#endif /* FBDP_DEBUG_OBJECT_NO_PAGER */

    queue_chain_t           cached_list;    /* 可持久化对象的缓存列表 */

    /* 以下字段不受任何锁保护，通过原子比较和交换更新 */
    vm_object_offset_t      last_alloc;     /* 最后一次分配的偏移量 */
    vm_offset_t             cow_hint;       /* 影子中存在但对象中不存在的最后一页 */
    int                     sequential;     /* 顺序访问大小 */

    uint32_t                pages_created;  /* 创建的页面数 */
    uint32_t                pages_used;     /* 使用的页面数 */

    unsigned int
    wimg_bits:8,                /* 缓存 WIMG 位 */
    code_signed:1,              /* 页面是否已签名 */
    transposed:1,               /* 对象是否被转置 */
    mapping_in_progress:1,      /* 分页器是否正在映射/取消映射 */
    phantom_isssd:1,
    volatile_empty:1,
    volatile_fault:1,
    all_reusable:1,
    blocked_access:1,
    set_cache_attr:1,
    object_is_shared_cache:1,
    purgeable_queue_type:2,
    purgeable_queue_group:3,
    io_tracking:1,
    no_tag_update:1,            /* 是否不更新标签 */
#if CONFIG_SECLUDED_MEMORY
    eligible_for_secluded:1,    /* 是否有资格使用隔离内存 */
    can_grab_secluded:1,        /* 是否可以抓取隔离内存 */
#else /* CONFIG_SECLUDED_MEMORY */
    __object3_unused_bits:2,
#endif /* CONFIG_SECLUDED_MEMORY */
#if VM_OBJECT_ACCESS_TRACKING
    access_tracking:1,          /* 是否启用访问跟踪 */
#else /* VM_OBJECT_ACCESS_TRACKING */
    __unused_access_tracking:1,
#endif /* VM_OBJECT_ACCESS_TRACKING */
    vo_ledger_tag:3,            /* 对象的分类标签 */
    vo_no_footprint:1;          /* 是否不计入内存占用 */

#if VM_OBJECT_ACCESS_TRACKING
    uint32_t        access_tracking_reads;  /* 访问跟踪的读取次数 */
    uint32_t        access_tracking_writes; /* 访问跟踪的写入次数 */
#endif /* VM_OBJECT_ACCESS_TRACKING */

    uint8_t                 scan_collisions; /* 扫描冲突次数 */
    uint8_t                 __object4_unused_bits[1]; /* 未使用的位 */
    vm_tag_t                wire_tag;        /* 固定页面的标签 */

#if CONFIG_PHANTOM_CACHE
    uint32_t                phantom_object_id; /* 幻影对象的 ID */
#endif
#if CONFIG_IOSCHED || UPL_DEBUG
    queue_head_t            uplq;            /* 未完成的 UPL 列表 */
#endif

#ifdef  VM_PIP_DEBUG
    /*
     * 跟踪持有 "paging_in_progress" 引用的第一个持有者的堆栈跟踪。
     */
#define VM_PIP_DEBUG_STACK_FRAMES       25      /* 每个堆栈跟踪的深度 */
#define VM_PIP_DEBUG_MAX_REFS           10      /* 跟踪的引用数 */
    struct __pip_backtrace {
        void *pip_retaddr[VM_PIP_DEBUG_STACK_FRAMES];
    } pip_holders[VM_PIP_DEBUG_MAX_REFS];
#endif  /* VM_PIP_DEBUG  */

    queue_chain_t           objq;            /* 对象队列 - 目前用于可清除队列 */
    queue_chain_t           task_objq;       /* 任务拥有的对象队列 - 受任务锁保护 */

#if !VM_TAG_ACTIVE_UPDATE
    queue_chain_t           wired_objq;      /* 固定对象队列 */
#endif /* !VM_TAG_ACTIVE_UPDATE */

#if DEBUG
    void *purgeable_owner_bt[16];            /* 可清除对象所有者的堆栈跟踪 */
    task_t vo_purgeable_volatilizer;         /* 使其易失的任务 */
    void *purgeable_volatilizer_bt[16];      /* 使其易失的堆栈跟踪 */
#endif /* DEBUG */
};

struct vm_page {
    union {
        vm_page_queue_chain_t vmp_q_pageq; /* 用于 FIFO 队列或空闲链表的队列信息（受页队列锁保护） */
        struct vm_page        *vmp_q_snext; /* 下一个页面的指针 */
    } vmp_q_un;

    vm_page_queue_chain_t vmp_listq;       /* 同一对象中的所有页面（受对象锁保护） */

    vm_page_queue_chain_t vmp_specialq;    /* 特殊队列中的匿名页面（受页队列锁保护） */
    vm_object_offset_t    vmp_offset;      /* 页面在对象中的偏移量（受对象锁和页队列锁保护） */

    vm_page_object_t      vmp_object;      /* 页面所属的对象（受对象锁和页队列锁保护），该物理页被使用时才有效 */

    /*
     * 以下标志字段过去由 "页队列" 锁保护。
     * 现在不再如此，具体需要什么锁取决于 vmp_q_state 的值。
     *
     * 如果启用了本地队列，我们使用 'vmp_wire_count' 来存储本地队列 ID。
     * 有关为什么这样做是安全的，请参阅 'vm_page_queues_remove' 的注释。
     */
#define VM_PAGE_SPECIAL_Q_EMPTY (0)
#define VM_PAGE_SPECIAL_Q_BG (1)
#define VM_PAGE_SPECIAL_Q_DONATE (2)
#define VM_PAGE_SPECIAL_Q_FG (3)
#define vmp_local_id vmp_wire_count
    unsigned int vmp_wire_count:16,        /* 有多少个固定映射使用此页面（受对象锁和页队列锁保护） */
                 vmp_q_state:4,            /* 页面所在的队列状态（受页队列锁保护），含：
                  空闲（Free）：页面未被使用，可以分配给新的内存请求。
                  活跃（Active）：页面正在被使用。
                  非活跃（Inactive）：页面不再被使用，但尚未被回收。
                  脏（Dirty）：页面已被修改，需要写回后备存储。
                  清理中（Cleaning）：页面正在被清理（写回后备存储）。
                  固定（Wired）：页面被固定，不能被换出。
 */
                 vmp_on_specialq:2,        /* 页面是否在特殊队列中 */
                 vmp_gobbled:1,            /* 页面被内部使用（受页队列锁保护） */
                 vmp_laundry:1,            /* 页面正在被清理（受页队列锁保护） */
                 vmp_no_cache:1,           /* 页面不应被缓存，应优先重用（受页队列锁保护） */
                 vmp_private:1,            /* 页面不应返回到空闲列表（受页队列锁保护） */
                 vmp_reference:1,          /* 页面已被使用（受页队列锁保护） */
                 vmp_lopage:1,             /* 页面是低优先级页面 */
                 vmp_realtime:1,           /* 页面被实时线程使用 */
#if !CONFIG_TRACK_UNMODIFIED_ANON_PAGES
                 vmp_unused_page_bits:3;   /* 未使用的位 */
#else /* ! CONFIG_TRACK_UNMODIFIED_ANON_PAGES */
                 vmp_unmodified_ro:1,      /* 跟踪匿名页面在解压缩后是否被修改（受对象锁和页队列锁保护） */
                 vmp_unused_page_bits:2;   /* 未使用的位 */
#endif /* ! CONFIG_TRACK_UNMODIFIED_ANON_PAGES */

    /*
     * 必须将这两个 32 位字的位字段分开，
     * 因为编译器有将它们视为单个 64 位字段的坏习惯。
     * 由于它们受不同的锁保护，这是一个真正的问题。
     */
    vm_page_packed_t vmp_next_m;           /* VP 桶链接（受对象锁保护） */

    /*
     * 以下标志字段受 "VM 对象" 锁保护。
     *
     * 重要提示：在持有 VM 对象 "共享" 锁和通过 pmap_lock_phys_page 函数获取的页面锁时，
     * 可以修改 "vmp_pmapped"、"vmp_xpmapped" 和 "vmp_clustered" 位。
     * 这是在 vm_fault_enter() 和 CONSUME_CLUSTERED 宏中完成的。
     * 也可以仅在 VM 对象 "独占" 锁下修改它们。
     */
    unsigned int vmp_busy:1,               /* 页面正在传输中（受对象锁保护） */
                 vmp_wanted:1,             /* 有人在等待此页面（受对象锁保护） */
                 vmp_tabled:1,             /* 页面在 VP 表中（受对象锁保护） */
                 vmp_hashed:1,             /* 页面在 vm_page_buckets[] 中（受对象锁和桶锁保护） */
                 vmp_fictitious:1,         /* 物理页面不存在（受对象锁保护） */
                 vmp_clustered:1,          /* 页面不是故障页面（受对象锁保护或对象共享锁和 pmap 页面锁保护） */
                 vmp_pmapped:1,            /* 页面已进入 pmap（受对象锁保护或对象共享锁和 pmap 页面锁保护） */
                 vmp_xpmapped:1,           /* 页面已以执行权限进入 pmap（受对象锁保护或对象共享锁和 pmap 页面锁保护） */
                 vmp_wpmapped:1,           /* 页面已以写权限进入 pmap（受对象锁保护） */
                 vmp_free_when_done:1,     /* 页面在清理完成后将被释放（受对象锁保护） */
                 vmp_absent:1,             /* 数据已被请求，但尚不可用（受对象锁保护） */
                 vmp_error:1,              /* 数据管理器由于错误无法提供数据（受对象锁保护） */
                 vmp_dirty:1,              /* 页面必须被清理（受对象锁保护） */
                 vmp_cleaning:1,           /* 页面清理已开始（受对象锁保护） */
                 vmp_precious:1,           /* 页面是宝贵的；即使干净也必须返回数据（受对象锁保护） */
                 vmp_overwriting:1,        /* 已发出解锁请求，但没有数据（受对象锁保护） */
                 vmp_restart:1,            /* 页面被 copy_call 相关的分页器推高到影子链中，需要重新从链的顶部开始 */
                 vmp_unusual:1,            /* 页面是缺席、错误、重启或页面锁定 */
                 vmp_cs_validated:VMP_CS_BITS, /* 代码签名：页面已通过验证 */
                 vmp_cs_tainted:VMP_CS_BITS,   /* 代码签名：页面被污染 */
                 vmp_cs_nx:VMP_CS_BITS,        /* 代码签名：页面是 nx */
                 vmp_reusable:1,               /* 页面可重用 */
                 vmp_written_by_kernel:1;      /* 页面由内核写入（例如解压缩） */

#if !defined(__arm64__)
    ppnum_t vmp_phys_page;                 /* 页面的物理页号 */
#endif
};

struct vm_map_copy {
#define VM_MAP_COPY_ENTRY_LIST          1 /* 连续的虚拟内存区域，支持遍历和释放 */
#define VM_MAP_COPY_KERNEL_BUFFER       2 /* 处理内核缓冲区中的复制数据，支持动态大小的分配和释放，最大支持2页，使用kalloc分配 */
    uint16_t                type;
    bool                    is_kernel_range;
    bool                    is_user_range;
    vm_map_range_id_t       orig_range;
    vm_object_offset_t      offset;
    vm_map_size_t           size;
    union {
        struct vm_map_header                  hdr;    /* ENTRY_LIST */
        void *XNU_PTRAUTH_SIGNED_PTR("vm_map_copy.kdata") kdata;  /* KERNEL_BUFFER */
    } c_u;
};

typedef struct memory_object {
    mo_ipc_object_bits_t mo_ikot; /* IPC 对象类型（不可更改） */

#if __LP64__
#if XNU_KERNEL_PRIVATE
    os_ref_atomic_t mo_ref;/* 在 LP64 架构上，有一个 4 字节的空洞，适合用作引用计数 */
#else
    unsigned int __mo_padding;/* 非内核私有代码中的填充字段 */
#endif /* XNU_KERNEL_PRIVATE */
#endif /* __LP64__ */

    const struct memory_object_pager_ops *mo_pager_ops; /* 分页器操作表 */

    memory_object_control_t mo_control; /* 内存对象控制 */
} *memory_object_t;

struct upl {
    decl_lck_mtx_data(, Lock);      /* 同步锁，用于保护 UPL 结构的并发访问 */
    int             ref_count;      /* 引用计数，表示当前有多少地方引用了该 UPL */
    int             ext_ref_count;  /* 外部引用计数，表示外部模块对该 UPL 的引用 */
    int             flags;          /* 标志位，用于存储 UPL 的状态和行为控制 */

    vm_object_offset_t u_offset;    /* UPL 在内存对象中的偏移量（字节对齐） */
    upl_size_t      u_size;         /* UPL 表示的地址空间大小（字节） */
    upl_size_t      u_mapped_size;  /* UPL 中已映射部分的大小（字节） */
    vm_offset_t     kaddr;          /* 内核中的二级映射地址 */
    vm_object_t     map_object;     /* 关联的内存对象（vm_object_t） */
    vector_upl_t    vector_upl;     /* 向量 UPL，用于支持多个 UPL 的聚合操作 */
    upl_t           associated_upl; /* 关联的 UPL，用于支持嵌套 UPL */
    struct upl_io_completion *upl_iodone; /* I/O 完成回调函数 */
    ppnum_t         highest_page;   /* UPL 中最高页面的物理页号（PPN） */

#if CONFIG_IOSCHED
    int             upl_priority;   /* UPL 的 I/O 优先级 */
    uint64_t        *upl_reprio_info; /* I/O 优先级调整信息 */
    void            *decmp_io_upl;  /* 解压缩 I/O 相关的 UPL */
#endif

#if CONFIG_IOSCHED || UPL_DEBUG
    thread_t        upl_creator;    /* 创建该 UPL 的线程 */
    queue_chain_t   uplq;           /* 对象上未完成 UPL 的链表 */
#endif

#if UPL_DEBUG
    uintptr_t       ubc_alias1;     /* 调试用：UBC（Unified Buffer Cache）别名 1 */
    uintptr_t       ubc_alias2;     /* 调试用：UBC 别名 2 */

    uint32_t        upl_state;      /* UPL 的当前状态 */
    uint32_t        upl_commit_index; /* 提交索引，用于调试 */
    uint32_t        upl_create_btref; /* 创建时的回溯引用（btref_t） */

    struct  ucd     upl_commit_records[UPL_DEBUG_COMMIT_RECORDS]; /* 提交记录 */
#endif  /* UPL_DEBUG */

    bitmap_t       *lite_list;      /* 轻量级页表列表 */
    struct upl_page_info page_list[]; /* 页面信息数组，存储 UPL 中每个页面的状态 */
};

vm_map_copy_t vm_map_copy_allocate(void); /* 从 vm_map_copies 区域中分配一个 vm_map_copy 对象 */


kern_return_t vm_map_copyin(vm_map_t src_map, vm_map_address_t src_addr, vm_map_size_t len, boolean_t src_destroy, vm_map_copy_t *copy_result); /* 从源地址空间复制内存并创建 vm_map_copy 对象 */
kern_return_t vm_map_copyin_kernel_buffer(vm_map_t src_map, vm_map_address_t src_addr, vm_map_size_t len, vm_map_copy_t *copy_result); /* 从内核缓冲区中复制数据并创建 vm_map_copy 对象 */

kern_return_t vm_map_copyout(vm_map_t dst_map, vm_map_address_t *dst_addr, vm_map_copy_t copy); /* 将 vm_map_copy 对象插入目标地址空间的未使用区域 */
kern_return_t vm_map_copy_overwrite(vm_map_t dst_map, vm_map_address_t dst_addr, vm_map_copy_t copy, boolean_t interruptible); /* 将 vm_map_copy 对象覆盖到目标地址空间的现有区域 */
kern_return_t vm_map_copy_overwrite_aligned(vm_map_t dst_map, vm_map_address_t dst_addr, vm_map_copy_t copy, boolean_t interruptible); /* 将 vm_map_copy 对象覆盖到目标地址空间的现有区域（确保对齐） */

void vm_map_copy_discard(vm_map_copy_t copy); /* 释放 vm_map_copy 对象及其关联的资源，比如复制失败时 */

void vm_map_copy_copy(vm_map_copy_t src_copy, vm_map_copy_t dst_copy); /* 将一个 vm_map_copy 对象的内容复制到另一个对象中 */

typedef const struct memory_object_pager_ops {
    /* 增加内存对象的引用计数 */
    void (*memory_object_reference)(memory_object_t mem_obj);

    /* 减少内存对象的引用计数，如果引用计数为 0，则释放内存对象 */
    void (*memory_object_deallocate)(memory_object_t mem_obj);

    /* 初始化内存对象 */
    kern_return_t (*memory_object_init)(
        memory_object_t mem_obj,                /* 内存对象 */
        memory_object_control_t mem_control,    /* 内存对象控制 */
        memory_object_cluster_size_t size       /* 内存对象大小 */
    );

    /* 终止内存对象 */
    kern_return_t (*memory_object_terminate)(memory_object_t mem_obj);

    /* 处理数据请求 */
    kern_return_t (*memory_object_data_request)(
        memory_object_t mem_obj,                /* 内存对象 */
        memory_object_offset_t offset,          /* 请求的偏移量 */
        memory_object_cluster_size_t length,    /* 请求的长度 */
        vm_prot_t desired_access,               /* 请求的访问权限 */
        memory_object_fault_info_t fault_info   /* 故障信息 */
    );

    /* 处理数据返回 */
    kern_return_t (*memory_object_data_return)(
        memory_object_t mem_obj,                /* 内存对象 */
        memory_object_offset_t offset,          /* 返回数据的偏移量 */
        memory_object_cluster_size_t size,      /* 返回数据的大小 */
        memory_object_offset_t *resid_offset,   /* 剩余偏移量 */
        int *io_error,                          /* I/O 错误 */
        boolean_t dirty,                        /* 数据是否脏 */
        boolean_t kernel_copy,                  /* 是否由内核复制 */
        int upl_flags                           /* UPL 标志 */
    );

    /* 初始化数据 */
    kern_return_t (*memory_object_data_initialize)(
        memory_object_t mem_obj,                /* 内存对象 */
        memory_object_offset_t offset,          /* 初始化数据的偏移量 */
        memory_object_cluster_size_t size       /* 初始化数据的大小 */
    );

#if XNU_KERNEL_PRIVATE
    /* 以下字段已废弃 */
    void *__obsolete_memory_object_data_unlock;
    void *__obsolete_memory_object_synchronize;
#else
    /* 解锁数据（已废弃） */
    kern_return_t (*memory_object_data_unlock)(
        memory_object_t mem_obj,
        memory_object_offset_t offset,
        memory_object_size_t size,
        vm_prot_t desired_access
    );

    /* 同步数据（已废弃） */
    kern_return_t (*memory_object_synchronize)(
        memory_object_t mem_obj,
        memory_object_offset_t offset,
        memory_object_size_t size,
        vm_sync_t sync_flags
    );
#endif /* !XNU_KERNEL_PRIVATE */

    /* 映射内存对象 */
    kern_return_t (*memory_object_map)(
        memory_object_t mem_obj,                /* 内存对象 */
        vm_prot_t prot                          /* 映射的保护权限 */
    );

    /* 最后一次取消映射 */
    kern_return_t (*memory_object_last_unmap)(memory_object_t mem_obj);

#if XNU_KERNEL_PRIVATE
    /* 以下字段已废弃 */
    void *__obsolete_memory_object_data_reclaim;
#else
    /* 回收数据（已废弃） */
    kern_return_t (*memory_object_data_reclaim)(
        memory_object_t mem_obj,
        boolean_t reclaim_backing_store
    );
#endif /* !XNU_KERNEL_PRIVATE */

    /* 获取内存对象的后备对象 */
    boolean_t (*memory_object_backing_object)(
        memory_object_t mem_obj,                /* 内存对象 */
        memory_object_offset_t mem_obj_offset,  /* 内存对象的偏移量 */
        vm_object_t *backing_object,            /* 后备对象 */
        vm_object_offset_t *backing_offset      /* 后备对象的偏移量 */
    );

    /* 分页器的名称 */
    const char *memory_object_pager_name;
} * memory_object_pager_ops_t;

/* 创建 UPL */
int ubc_create_upl(vnode_t vp, off_t offset, int size, upl_t *upl); // 为 vnode 创建新的 UPL，填充其 vm_object（在 Darwin 17 中移除）。
int ubc_create_upl_external(vnode_t vp, off_t offset, int size, upl_t *upl); // 同上，但用于外部（kext）调用者。
int ubc_create_upl_kernel(vnode_t vp, off_t offset, int size, upl_t *upl); // 同上，但用于内核内部使用。
int vm_map_create_upl(vm_map_t map, vm_map_offset_t offset, vm_map_size_t size, upl_t *upl); // 由 VM 映射处理层调用以创建 UPL。
int vm_object_upl_request(vm_object_t object, vm_object_offset_t offset, vm_object_size_t size, upl_t *upl); // 由 VM 对象处理层调用以请求 UPL。
int vm_object_iopl_request(vm_object_t object, vm_object_offset_t offset, vm_object_size_t size, upl_t *upl); // 由 VM 对象处理层调用以请求 I/O UPL。
int memory_object_upl_request(memory_object_t pager, memory_object_offset_t offset, memory_object_size_t size, upl_t *upl); // 由分页器调用以请求 UPL。
int memory_object_iopl_request(memory_object_t pager, memory_object_offset_t offset, memory_object_size_t size, upl_t *upl); // 由分页器调用以请求 I/O UPL。
int vector_upl_create(int count, upl_t *upl); // 由 VFS 层的 cluster_[write/read]_direct 使用以创建向量 UPL。

/* 操作UPL */
int ubc_upl_abort(upl_t upl); // 中止（丢弃）整个 UPL 中的页面。
int ubc_upl_abort_range(upl_t upl, int offset, int size); // 中止（丢弃）UPL 中指定范围的页面。
int ubc_upl_commit(upl_t upl); // 提交（将页面刷新到后备存储）整个 UPL。
int ubc_upl_commit_range(upl_t upl, int offset, int size); // 提交（将页面刷新到后备存储）UPL 中指定范围的页面。
int ubc_upl_map(upl_t upl, vm_map_t map, vm_map_offset_t *addr); // 将关联的页面列表映射到内核虚拟地址空间。
int ubc_upl_unmap(upl_t upl); // 将关联的页面列表从内核虚拟地址空间中取消映射。
int ubc_upl_pageinfo(upl_t upl, upl_page_info_t *page_info); // 检索标记为 UPL_INTERNAL 的 UPL 的内部页面列表。
int ubc_upl_range_needed(upl_t upl, int offset, int size); // 指定所需的页面范围。

/* 释放UPL */
void upl_destroy(upl_t upl); // 销毁 UPL 并释放其内存（如果引用计数为零）。
void upl_deallocate(upl_t upl); // 释放 UPL 并可选调用 upl_callout_iodone()。