zx_object_get_info

摘要

物件查詢資訊。

宣告

#include <zircon/syscalls.h>

zx_status_t zx_object_get_info(zx_handle_t handle,
                               uint32_t topic,
                               void* buffer,
                               size_t buffer_size,
                               size_t* actual,
                               size_t* avail);

說明

zx_object_get_info() 會要求所提供帳號代碼 (或 處理常式所參照的物件)。topic 參數代表 所需的資訊

buffer 是一個指標,指向大小 buffer_size 的緩衝區,以便傳回 可能不準確或不適當

「實際」是一個選用指標,用於傳回已產生的記錄數量 寫入緩衝區。

avail 是選用指標,用於傳回已產生的記錄數 讀取。

如果緩衝區空間不足,播映資訊會大於實際值。

主題

ZX_INFO_HANDLE_VALID

handle 類型:Any

buffer 類型:n/a

如果 handle 有效,會傳回 ZX_OK,否則傳回 ZX_ERR_BAD_HANDLE。否 ,但 buffer 可能為 NULL。

ZX_INFO_HANDLE_BASIC

handle 類型:Any

buffer 類型:zx_info_handle_basic_t[1]

typedef struct zx_info_handle_basic {
    // The unique id assigned by kernel to the object referenced by the
    // handle.
    zx_koid_t koid;

    // The immutable rights assigned to the handle. Two handles that
    // have the same koid and the same rights are equivalent and
    // interchangeable.
    zx_rights_t rights;

    // The object type: channel, event, socket, etc.
    uint32_t type;                // zx_obj_type_t;

    // If the object referenced by the handle is related to another (such
    // as the other end of a channel, or the parent of a job) then
    // |related_koid| is the koid of that object, otherwise it is zero.
    // This relationship is immutable: an object's |related_koid| does
    // not change even if the related object no longer exists.
    zx_koid_t related_koid;
} zx_info_handle_basic_t;

ZX_INFO_HANDLE_COUNT

handle 類型:Any

buffer 類型:zx_info_handle_count_t[1]

typedef struct zx_info_handle_count {
    // The number of outstanding handles to a kernel object.
    uint32_t handle_count;
} zx_info_handle_count_t;

handle_count 只能做為偵錯輔助使用,請勿用於 檢查不受信任的程序無法修改核心物件。因為 可能是系統排程器非同步作業 就算先前的處理常式擁有者修改物件 即使最後一個帳號代碼移轉到其他程序時也一樣。

ZX_INFO_PROCESS_HANDLE_STATS

handle 類型:Process

buffer 類型:zx_info_process_handle_stats_t[1]

typedef struct zx_info_process_handle_stats {
    // The number of outstanding handles to kernel objects of each type.
    uint32_t handle_count[ZX_OBJ_TYPE_UPPER_BOUND];
} zx_info_process_handle_stats_t;

ZX_INFO_HANDLE_TABLE

handle 類型:Process

buffer 類型:zx_info_handle_extended_t[n]

針對 zx_info_handle_extended_t 中的每個控點,傳回一個陣列 通話期間處理中。核心可確保傳回的控點 保持一致性。

typedef struct zx_info_handle_extended {
    // The object type: channel, event, socket, etc.
    zx_obj_type_t type;

    // The handle value, which is only valid for the process that
    // was passed to ZX_INFO_HANDLE_TABLE.
    zx_handle_t handle_value;

    // The immutable rights assigned to the handle. Two handles that
    // have the same koid and the same rights are equivalent and
    // interchangeable.
    zx_rights_t rights;

    uint32_t reserved;

    // The unique id assigned by kernel to the object referenced by the
    // handle.
    zx_koid_t koid;

    // If the object referenced by the handle is related to another (such
    // as the other end of a channel, or the parent of a job) then
    // |related_koid| is the koid of that object, otherwise it is zero.
    // This relationship is immutable: an object's |related_koid| does
    // not change even if the related object no longer exists.
    zx_koid_t related_koid;

    // If the object referenced by the handle has a peer, like the
    // other end of a channel, then this is the koid of the process
    // which currently owns it.
    zx_koid_t peer_owner_koid;
} zx_info_handle_extended_t;

請注意,程序可能包含物件的即時參照, 沒有控制代碼舉例來說,若執行適用於所有程序的執行緒 已關閉

ZX_INFO_JOB

handle 類型:Job

buffer 類型:zx_info_job_t[1]

typedef struct zx_info_job {
    // The job's return code; only valid if |exited| is true.
    // If the code is valid, it will be one of the ZX_TASK_RETCODE values.
    int64_t return_code;

    // If true, the job has exited and |return_code| is valid.
    // Killing a job is the only way for a job to exit.
    bool exited;

    // True if the ZX_PROP_JOB_KILL_ON_OOM property was set.
    bool kill_on_oom;

    // True if a debugger is attached to the job.
    bool debugger_attached;
} zx_info_job_t;

請注意,|已關閉|將立即報告,指出工作已結束 |zx_task_kill|或同等事件 (例如 OOM 終止事件),但子項工作和程序 可能還在退出。

ZX_INFO_PROCESS

handle 類型:Process

buffer 類型:zx_info_process_t[1]

typedef struct zx_info_process {
    // The process's return code; only valid if the
    // |ZX_PROCESS_INFO_FLAG_EXITED| flag is set. If the process was killed, it
    // will be one of the |ZX_TASK_RETCODE| values.
    int64_t return_code;

    // The monotonic time at which `zx_process_start()` was called, only valid
    // if the |ZX_INFO_PROCESS_FLAG_STARTED| flag is set.
    zx_time_t start_time;

    // Bitwise OR of ZX_INFO_PROCESS_FLAG_* values.
    uint32_t flags;
} zx_info_process_t;

請注意,|flags|會立即回報程序已結束 (亦即 將含有 ZX_INFO_PROCESS_FLAG_EXITED,並出現在 |zx_task_kill|,但子項 執行緒可能還在離開中。

ZX_INFO_PROCESS_THREADS

handle 類型:Process

buffer 類型:zx_koid_t[n]

傳回 zx_koid_t 的陣列,程序中的每個執行中的執行緒各有一個陣列,網址為 當下的一切

北取得執行緒清單本質上是強制性的。包括一些 先暫停所有執行緒來減輕影響,但請注意外部執行緒 建立新的討論串actual 值含有 bufferavail 則包含 則可能會大於實際

ZX_INFO_THREAD

handle 類型:Thread

buffer 類型:zx_info_thread_t[1]

typedef struct zx_info_thread {
    // One of ZX_THREAD_STATE_* values.
    uint32_t state;

    // If |state| is ZX_THREAD_STATE_BLOCKED_EXCEPTION, the thread has gotten
    // an exception and is waiting for the exception to be handled by the
    // specified channel.
    // The value is one of ZX_EXCEPTION_CHANNEL_TYPE_*.
    uint32_t wait_exception_channel_type;

    // CPUs this thread may be scheduled on, as specified by
    // a profile object applied to this thread.
    //
    // The kernel may not internally store invalid CPUs in the mask, so
    // this may not exactly match the mask applied to the thread for
    // CPUs beyond what the system is able to use.
    zx_cpu_set_t cpu_affinity_mask;
} zx_info_thread_t;

這個結構中的值主要用於資訊和偵錯 時刻。

各種 ZX_THREAD_STATE_ 值是由

#include <zircon/syscalls/object.h>
  • ZX_THREAD_STATE_NEW:執行緒已建立,但尚未開始 執行中。
  • ZX_THREAD_STATE_RUNNING:執行緒正常執行使用者程式碼。
  • ZX_THREAD_STATE_SUSPENDED:因zx_task_suspend()而停止。
  • ZX_THREAD_STATE_BLOCKED:在系統呼叫或處理例外狀況中。這個 值本身一律不會傳回。請參閱下方的「ZX_THREAD_STATEBLOCKED」*。
  • ZX_THREAD_STATE_DYING:執行緒正在終止中, 但尚未停止。
  • ZX_THREAD_STATE_DEAD:執行緒已停止執行。

當執行緒在阻塞的 sys 呼叫 中停止,或在例外狀況中停止時, state 中傳回的值會是下列其中一個值:

各種 ZX_EXCEPTION_CHANNEL_TYPE_ 值是由

#include <zircon/syscalls/exception.h>
  • ZX_EXCEPTION_CHANNEL_TYPE_NONE
  • ZX_EXCEPTION_CHANNEL_TYPE_DEBUGGER
  • ZX_EXCEPTION_CHANNEL_TYPE_THREAD
  • ZX_EXCEPTION_CHANNEL_TYPE_PROCESS
  • ZX_EXCEPTION_CHANNEL_TYPE_JOB
  • ZX_EXCEPTION_CHANNEL_TYPE_JOB_DEBUGGER

ZX_INFO_THREAD_EXCEPTION_REPORT

handle 類型:Thread

buffer 類型:zx_exception_report_t[1]

#include <zircon/syscalls/exception.h>

如果執行緒目前是例外狀況,正在等待例外狀況 回應,則此回應會將例外狀況報表傳回為 zx_exception_report_t,狀態為ZX_OK

如果執行緒不在例外狀況中並等待,則會傳回 ZX_ERR_BAD_STATE 取得例外狀況回應。

ZX_INFO_THREAD_STATS

handle 類型:Thread

buffer 類型:zx_info_thread_stats[1]

typedef struct zx_info_thread_stats {
    // Total accumulated running time of the thread.
    //
    // Note: See zx_info_task_runtime for queue time in addition to runtime.
    zx_duration_t total_runtime;

    // CPU number that this thread was last scheduled on, or ZX_INFO_INVALID_CPU
    // if the thread has never been scheduled on a CPU. By the time this call
    // returns, the thread may have been scheduled elsewhere, so this
    // information should only be used as a hint or for statistics.
    uint32_t last_scheduled_cpu;
} zx_info_thread_stats_t;

如果執行緒已結束,則傳回 ZX_ERR_BAD_STATE

ZX_INFO_GUEST_STATS

handle 類型:Resource (具體來說,是資訊資源)

buffer 類型:zx_info_guest_stats_t[1]

// Each machine has its own format for the same ZX_INFO_GUEST_STATS topic.
// In each build, zx_info_guest_stats_t is a typedef alias for the type.
// Cross-tools can select the machine-specific type to use based on the
// source of the data they are working with.
typedef struct zx_arm64_info_guest_stats {
    uint32_t cpu_number;
    uint32_t flags;
    uint64_t vm_entries;
    uint64_t vm_exits;
    uint64_t wfi_wfe_instructions;
    uint64_t instruction_aborts;
    uint64_t data_aborts;
    uint64_t system_instructions;
    uint64_t smc_instructions;
    uint64_t interrupts;
} zx_arm64_info_guest_stats_t;

typedef struct zx_x86_64_info_guest_stats {
    uint32_t cpu_number;
    uint32_t flags;
    uint64_t vm_entries;
    uint64_t vm_exits;
    uint64_t interrupts;
    uint64_t interrupt_windows;
    uint64_t cpuid_instructions;
    uint64_t hlt_instructions;
    uint64_t control_register_accesses;
    uint64_t io_instructions;
    uint64_t rdmsr_instructions;
    uint64_t wrmsr_instructions;
    uint64_t ept_violations;
    uint64_t xsetbv_instructions;
    uint64_t pause_instructions;
    uint64_t vmcall_instructions;
} zx_x86_64_info_guest_stats;

ZX_INFO_CPU_STATS

handle 類型:Resource (具體來說,是資訊資源)

buffer 類型:zx_info_cpu_stats_t[1]

typedef struct zx_info_cpu_stats {
    uint32_t cpu_number;
    uint32_t flags;

    zx_duration_t idle_time;

    // kernel scheduler counters
    uint64_t reschedules;
    uint64_t context_switches;
    uint64_t irq_preempts;
    uint64_t preempts;
    uint64_t yields;

    // cpu level interrupts and exceptions
    uint64_t ints;          // hardware interrupts, minus timer interrupts
                            // inter-processor interrupts
    uint64_t timer_ints;    // timer interrupts
    uint64_t timers;        // timer callbacks
    uint64_t page_faults;   // (deprecated, returns 0)
    uint64_t exceptions;    // (deprecated, returns 0)
    uint64_t syscalls;

    // inter-processor interrupts
    uint64_t reschedule_ipis;
    uint64_t generic_ipis;
} zx_info_cpu_stats_t;

ZX_INFO_VMAR

handle 類型:VM Address Region

buffer 類型:zx_info_vmar_t[1]

typedef struct zx_info_vmar {
    // Base address of the region.
    uintptr_t base;

    // Length of the region, in bytes.
    size_t len;
} zx_info_vmar_t;

這會傳回一個說明位址空間範圍的單一 zx_info_vmar_t VMAR 會佔用的資源

ZX_INFO_VMAR_MAPS

handle 類型:Vm Address Region,使用 ZX_RIGHT_INSPECT

buffer 類型:zx_info_maps_t[n]

zx_info_maps_t 陣列是深度優先預購的目標 VMAR 樹狀結構。根據預購週遊基礎地址,系統會以遞增順序排列。

如需 zx_info_maps_t 的說明,請參閱 ZX_INFO_PROCESS_MAPS

第一個 zx_info_maps_t 會描述查詢的 VMAR。深度 每個項目的欄位說明其與來源節點之間的關係 。所查詢 VMAR 的深度為 0。所有其他項目 深度為 1 以上

其他錯誤:

  • ZX_ERR_ACCESS_DENIED:缺少相關權利時。
  • ZX_ERR_BAD_STATE:如果 VMAR 或包含 VMAR 的位址空間 應已刪除,或含有 VMAR 的程序已終止。

ZX_INFO_VMO

handle 類型:VM Object

buffer 類型:zx_info_vmo_t[1]

typedef struct zx_info_vmo {
    // The koid of this VMO.
    zx_koid_t koid;

    // The name of this VMO.
    char name[ZX_MAX_NAME_LEN];

    // The size of this VMO; i.e., the amount of virtual address space it
    // would consume if mapped.
    uint64_t size_bytes;

    // If this VMO is a child , the koid of its parent. Otherwise, zero.
    // See |flags| for the type of child.
    zx_koid_t parent_koid;

    // The number of children of this VMO, if any.
    size_t num_children;

    // The number of times this VMO is currently mapped into VMARs.
    // Note that the same process will often map the same VMO twice,
    // and both mappings will be counted here. (I.e., this is not a count
    // of the number of processes that map this VMO; see share_count.)
    size_t num_mappings;

    // An estimate of the number of unique address spaces that
    // this VMO is mapped into. Every process has its own address space,
    // and so does the kernel.
    size_t share_count;

    // Bitwise OR of ZX_INFO_VMO_* values.
    uint32_t flags;

    // If |ZX_INFO_VMO_TYPE(flags) == ZX_INFO_VMO_TYPE_PAGED|, the amount of
    // memory currently allocated to this VMO; i.e., the amount of physical
    // memory it consumes. Undefined otherwise.
    uint64_t committed_bytes;

    // If |flags & ZX_INFO_VMO_VIA_HANDLE|, the handle rights.
    //
    // If |flags & ZX_INFO_VMO_VIA_IOB_HANDLE|, the effective combined
    // handle rights for the IOB region and containing IOB.
    //
    // Undefined otherwise.
    zx_rights_t handle_rights;

    // VMO mapping cache policy. One of ZX_CACHE_POLICY_*
    uint32_t cache_policy;

    // Amount of kernel memory, in bytes, allocated to track metadata
    // associated with this VMO.
    uint64_t metadata_bytes;

    // Running counter of the number of times the kernel, without user request,
    // performed actions on this VMO that would have caused |committed_bytes| to
    // report a different value.
    uint64_t committed_change_events;

    // If |ZX_INFO_VMO_TYPE(flags) == ZX_INFO_VMO_TYPE_PAGED|, the amount of
    // content that has been populated and is being tracked by this vmo. This
    // can be greater than |committed_bytes| where content might be compressed
    // or otherwise tracked in a way that does not correlate directly to being
    // committed.
    uint64_t populated_bytes;
} zx_info_vmo_t;

這會傳回一個 zx_info_vmo_t,用來說明 VMO。

ZX_INFO_SOCKET

handle 類型:Socket

buffer 類型:zx_info_socket_t[1]

typedef struct zx_info_socket {
    // The options passed to zx_socket_create().
    uint32_t options;

    // The maximum size of the receive buffer of a socket, in bytes.
    //
    // The receive buffer may become full at a capacity less than the maximum
    // due to overhead.
    size_t rx_buf_max;

    // The size of the receive buffer of a socket, in bytes.
    size_t rx_buf_size;

    // The amount of data, in bytes, that is available for reading in a single
    // zx_socket_read call.
    //
    // For stream sockets, this value will match |rx_buf_size|. For datagram
    // sockets, this value will be the size of the next datagram in the receive
    // buffer.
    size_t rx_buf_available;

    // The maximum size of the transmit buffer of a socket, in bytes.
    //
    // The transmit buffer may become full at a capacity less than the maximum
    // due to overhead.
    //
    // Will be zero if the peer endpoint is closed.
    size_t tx_buf_max;

    // The size of the transmit buffer of a socket, in bytes.
    //
    // Will be zero if the peer endpoint is closed.
    size_t tx_buf_size;
} zx_info_socket_t;

ZX_INFO_TIMER

handle 類型:Timer

buffer 類型:zx_info_timer_t[1]

typedef struct zx_info_timer {
    // The options passed to zx_timer_create().
    uint32_t options;

    // The deadline with respect to ZX_CLOCK_MONOTONIC at which the timer will
    // fire next.
    //
    // This value will be zero if the timer is not set to fire.
    zx_time_t deadline;

    // Specifies a range from deadline - slack to deadline + slack during which
    // the timer is allowed to fire. The system uses this parameter as a hint to
    // coalesce nearby timers.
    //
    // The precise coalescing behavior is controlled by the options parameter
    // specified when the timer was created.
    //
    // This value will be zero if the timer is not set to fire.
    zx_duration_t slack;
} zx_info_timer_t;

ZX_INFO_JOB_CHILDREN

handle 類型:Job

buffer 類型:zx_koid_t[n]

傳回 zx_koid_t 的陣列,提供的提供的每個直接子項工作各有一個陣列 工作控制代碼。

ZX_INFO_JOB_PROCESSES

handle 類型:Job

buffer 類型:zx_koid_t[n]

傳回 zx_koid_t 的陣列, 所提供的工作控制代碼

ZX_INFO_TASK_STATS

handle 類型:Process

buffer 類型:zx_info_task_stats_t[1]

傳回工作所用資源 (例如記憶體) 的統計資料。

typedef struct zx_info_task_stats {
    // The total size of mapped memory ranges in the task.
    // Not all will be backed by physical memory.
    size_t mem_mapped_bytes;

    // For the fields below, a byte is considered committed if it's backed by
    // physical memory. Some of the memory may be double-mapped, and thus
    // double-counted.

    // Committed memory that is only mapped into this task.
    size_t mem_private_bytes;

    // Committed memory that is mapped into this and at least one other task.
    size_t mem_shared_bytes;

    // A number that estimates the fraction of mem_shared_bytes that this
    // task is responsible for keeping alive.
    //
    // An estimate of:
    //   For each shared, committed byte:
    //   mem_scaled_shared_bytes += 1 / (number of tasks mapping this byte)
    //
    // This number is strictly smaller than mem_shared_bytes.
    size_t mem_scaled_shared_bytes;
} zx_info_task_stats_t;

其他錯誤:

  • ZX_ERR_BAD_STATE:如果目標程序已終止

ZX_INFO_TASK_RUNTIME

handle 類型:JobProcessThread

buffer 類型:zx_info_task_runtime_t[1]

傳回工作執行階段的相關統計資料。

// Info on the runtime of a task.
typedef struct zx_info_task_runtime {
    // The total amount of time this task and its children were
    // running on a CPU (not blocked).
    // * Threads include only their own runtime.
    // * Processes include the runtime for all of their threads (including threads that previously
    // exited).
    // * Jobs include the runtime for all of their processes (including processes that previously
    // exited).
    zx_duration_t cpu_time;

    // The total amount of time this task and its children were queued
    // to run (ready) but not actually using a CPU.
    // * Threads include only their own queue time.
    // * Processes include the queue time for all of their threads (including threads that
    // previously exited).
    // * Jobs include the queue time for all of their processes (including processes that previously
    // exited).
    zx_duration_t queue_time;

    // The total amount of time this task and its children spent handling page faults.
    // * Threads include only their own page fault handling time.
    // * Processes include the page fault time for all of their threads (including threads that
    // previously exited).
    // * Jobs include the page fault time for all of their processes (including processes that
    // previously exited).
    zx_duration_t page_fault_time;

    // The total amount of time this task and its children spent waiting on contended kernel locks.
    // * Threads include only their own wait time.
    // * Processes include the wait time for all of their threads (including threads that
    // previously exited).
    // * Jobs include the wait time for all of their processes (including processes that
    // previously exited).
    zx_duration_t lock_contention_time;
} zx_info_task_runtime_t;

工作的執行時間不包含暫停或封鎖的時間 等待事件或 I/O 作業這些統計資料可能會用於:

  1. 估算工作已使用的 CPU 作業時間。
  2. 估算工作因其他工作而造成的延遲時間 (佇列) 網頁錯誤處理常式,以及核心鎖定爭用情形。

ZX_INFO_PROCESS_MAPS

handle 類型:Process,使用 ZX_RIGHT_READ

buffer 類型:zx_info_maps_t[n]

zx_info_maps_t 陣列是深度優先預購的目標 程序的 Aspace/VMAR/對應樹狀結構與預購週遊的基準資料相同 會以遞增順序排列。

typedef struct zx_info_maps {
    // Name if available; empty string otherwise.
    char name[ZX_MAX_NAME_LEN];
    // Base address.
    zx_vaddr_t base;
    // Size in bytes.
    size_t size;

    // The depth of this node in the tree.
    // Can be used for indentation, or to rebuild the tree from an array
    // of zx_info_maps_t entries, which will be in depth-first pre-order.
    size_t depth;
    // The type of this entry; indicates which union entry is valid.
    uint32_t type; // zx_info_maps_type_t
    union {
        zx_info_maps_mapping_t mapping;
        // No additional fields for other types.
    } u;
} zx_info_maps_t;

typedef struct zx_info_maps_mapping {
    // MMU flags for the mapping.
    // Bitwise OR of ZX_VM_PERM_{READ,WRITE,EXECUTE} values.
    zx_vm_option_t mmu_flags;
    uint8_t padding1[4];
    // koid of the mapped VMO or IOB region.
    zx_koid_t vmo_koid;
    // Offset into the above VMO or IOB region.
    uint64_t vmo_offset;
    // The number of PAGE_SIZE pages in the mapped region of the VMO or
    // IOB region that are backed by physical memory.
    size_t committed_pages;
    // The number of PAGE_SIZE pages of content that have been populated and are
    // being tracked in the mapped region of the VMO or IOB region. This can be
    // greater than |committed_pages| where pages might be compressed or otherwise
    // tracked in a way that does not correlate directly to being committed.
    size_t populated_pages;
} zx_info_maps_mapping_t;

每個項目的 depth 欄位會說明本身與節點之間關係的關係 。深度 0 是根命名空間,深度 1 是根 VMAR,而所有 或是其他符記的深度 2 以上。

為了全面瞭解程序的 VMO 使用方式,以及 VMO 如何用於 多個程序,您可能需要將這些資訊 ZX_INFO_PROCESS_VMOS.

請參閱 vmaps 指令列工具,以取得這個主題的範例使用者並傾印 可依據 koid 屬性對應任意程序的對應

其他錯誤:

  • ZX_ERR_ACCESS_DENIED:缺少相關權利時。
  • ZX_ERR_BAD_STATE:如果目標程序已終止,或 位址空間已刪除

ZX_INFO_PROCESS_VMOS

handle 類型:Process,使用 ZX_RIGHT_READ

buffer 類型:zx_info_vmo_t[n]

zx_info_vmo_t 陣列會列出目標指向的所有 VMO 清單 上傳資料集之後,您可以運用 AutoML 自動完成部分資料準備工作會對應部分 VMO,部分 VMO 會指向 VMO 或 IOB 部分,有些則屬於此類。flags 所傳回結構中的 欄位,會指出其中一個 ZX_INFO_VMO_VIA_HANDLE、ZX_INFO_VMO_VIA_IOB_HANDLE,或 ZX_INFO_VMO_VIA_MAPPING 表示允許差異。

為了全面瞭解程序的 VMO 使用方式,以及 VMO 如何用於 多個程序,您可能需要將這些資訊 ZX_INFO_PROCESS_MAPS.

// Describes a VMO.
typedef struct zx_info_vmo {
    // The koid of this VMO.
    zx_koid_t koid;

    // The name of this VMO.
    char name[ZX_MAX_NAME_LEN];

    // The size of this VMO; i.e., the amount of virtual address space it
    // would consume if mapped.
    uint64_t size_bytes;

    // If this VMO is a child , the koid of its parent. Otherwise, zero.
    // See |flags| for the type of child.
    zx_koid_t parent_koid;

    // The number of children of this VMO, if any.
    size_t num_children;

    // The number of times this VMO is currently mapped into VMARs.
    // Note that the same process will often map the same VMO twice,
    // and both mappings will be counted here. (I.e., this is not a count
    // of the number of processes that map this VMO; see share_count.)
    size_t num_mappings;

    // An estimate of the number of unique address spaces that
    // this VMO is mapped into. Every process has its own address space,
    // and so does the kernel.
    size_t share_count;

    // Bitwise OR of ZX_INFO_VMO_* values.
    uint32_t flags;

    // If |ZX_INFO_VMO_TYPE(flags) == ZX_INFO_VMO_TYPE_PAGED|, the amount of
    // memory currently allocated to this VMO; i.e., the amount of physical
    // memory it consumes. Undefined otherwise.
    uint64_t committed_bytes;

    // If |flags & ZX_INFO_VMO_VIA_HANDLE|, the handle rights.
    //
    // If |flags & ZX_INFO_VMO_VIA_IOB_HANDLE|, the effective combined
    // handle rights for the IOB region and containing IOB.
    //
    // Undefined otherwise.
    zx_rights_t handle_rights;

    // VMO mapping cache policy. One of ZX_CACHE_POLICY_*
    uint32_t cache_policy;

    // Amount of kernel memory, in bytes, allocated to track metadata
    // associated with this VMO.
    uint64_t metadata_bytes;

    // Running counter of the number of times the kernel, without user request,
    // performed actions on this VMO that would have caused |committed_bytes| to
    // report a different value.
    uint64_t committed_change_events;

    // If |ZX_INFO_VMO_TYPE(flags) == ZX_INFO_VMO_TYPE_PAGED|, the amount of
    // content that has been populated and is being tracked by this vmo. This
    // can be greater than |committed_bytes| where content might be compressed
    // or otherwise tracked in a way that does not correlate directly to being
    // committed.
    uint64_t populated_bytes;
} zx_info_vmo_t;

請參閱 vmos 指令列工具,以取得這個主題的範例使用者並傾印 可依據 koid 建立任意程序的 VMO

ZX_INFO_KMEM_STATS

handle 類型:Resource (具體來說,是資訊資源)

buffer 類型:zx_info_kmem_stats_t[1]

傳回核心記憶體用量的相關資訊。

typedef struct zx_info_kmem_stats {
    // The total amount of physical memory available to the system.
    // Note, the values below may not exactly add up to this total.
    size_t total_bytes;

    // The amount of unallocated memory.
    size_t free_bytes;

    // The amount of memory reserved by and mapped into the kernel for reasons
    // not covered by other fields in this struct. Typically for readonly data
    // like the ram disk and kernel image, and for early-boot dynamic memory.
    size_t wired_bytes;

    // The amount of memory allocated to the kernel heap.
    size_t total_heap_bytes;

    // The portion of |total_heap_bytes| that is not in use.
    size_t free_heap_bytes;

    // The amount of memory committed to VMOs, both kernel and user.
    // A superset of all userspace memory.
    // Does not include certain VMOs that fall under |wired_bytes|.
    size_t vmo_bytes;

    // The amount of memory used for architecture-specific MMU metadata
    // like page tables.
    size_t mmu_overhead_bytes;

    // Non-free memory that isn't accounted for in any other field.
    size_t other_bytes;
} zx_info_kmem_stats_t;

ZX_INFO_KMEM_STATS_EXTENDED

handle 類型:Resource (具體來說,是資訊資源)

buffer 類型:zx_info_kmem_stats_extended_t[1]

傳回核心記憶體用量的相關資訊,包含 包括 ZX_INFO_KMEM_STATS 主題,以及更多 最昂貴的收集成本

typedef struct zx_info_kmem_stats_extended {
    // The total amount of physical memory available to the system.
    uint64_t total_bytes;

    // The amount of unallocated memory.
    uint64_t free_bytes;

    // The amount of memory reserved by and mapped into the kernel for reasons
    // not covered by other fields in this struct. Typically for readonly data
    // like the ram disk and kernel image, and for early-boot dynamic memory.
    uint64_t wired_bytes;

    // The amount of memory allocated to the kernel heap.
    uint64_t total_heap_bytes;

    // The portion of |total_heap_bytes| that is not in use.
    uint64_t free_heap_bytes;

    // The amount of memory committed to VMOs, both kernel and user.
    // A superset of all userspace memory.
    // Does not include certain VMOs that fall under |wired_bytes|.
    uint64_t vmo_bytes;

    // The amount of memory committed to pager-backed VMOs.
    uint64_t vmo_pager_total_bytes;

    // The amount of memory committed to pager-backed VMOs, that has been most
    // recently accessed, and would not be eligible for eviction by the kernel
    // under memory pressure.
    uint64_t vmo_pager_newest_bytes;

    // The amount of memory committed to pager-backed VMOs, that has been least
    // recently accessed, and would be the first to be evicted by the kernel
    // under memory pressure.
    uint64_t vmo_pager_oldest_bytes;

    // The amount of memory committed to discardable VMOs that is currently
    // locked, or unreclaimable by the kernel under memory pressure.
    uint64_t vmo_discardable_locked_bytes;

    // The amount of memory committed to discardable VMOs that is currently
    // unlocked, or reclaimable by the kernel under memory pressure.
    uint64_t vmo_discardable_unlocked_bytes;

    // The amount of memory used for architecture-specific MMU metadata
    // like page tables.
    uint64_t mmu_overhead_bytes;

    // The amount of memory in use by IPC.
    uint64_t ipc_bytes;

    // Non-free memory that isn't accounted for in any other field.
    uint64_t other_bytes;

    // The amount of memory in VMOs that would otherwise be tracked for
    // reclamation, but has had reclamation disabled.
    uint64_t vmo_reclaim_disabled_bytes;
} zx_info_kmem_stats_extended_t;

ZX_INFO_KMEM_STATS_COMPRESSION

handle 類型:Resource (具體來說,是資訊資源)

buffer 類型:zx_info_kmem_stats_compression_t[1]

傳回與壓縮作業有關的核心記憶體用量資訊 記憶體子系統

typedef struct zx_info_kmem_stats_compression {
    // Size in bytes of the content that is currently being compressed and stored.
    uint64_t uncompressed_storage_bytes;

    // Size in bytes of all memory, including metadata, fragmentation and other
    // overheads, of the compressed memory area. Note that due to base book
    // keeping overhead this could be non-zero, even when
    // |uncompressed_content_bytes| is zero.
    uint64_t compressed_storage_bytes;

    // Size in bytes of any fragmentation in the compressed memory area.
    uint64_t compressed_fragmentation_bytes;

    // Total amount of CPU time spent on compression across all threads.
    // Compression may happen in parallel and so this can be larger than
    // wall clock time.
    zx_duration_t compression_time;

    // Total amount of time decompression has spent on a CPU across all threads.
    // Decompression may happen in parallel and so this can increase faster than
    // wall clock time.
    zx_duration_t decompression_time;

    // Total number of times compression has been done on a page, regardless of
    // whether the compressed result was ultimately retained.
    uint64_t total_page_compression_attempts;

    // How many of the total compression attempts were considered failed and
    // were not stored. An example reason for failure would be a page not being
    // compressed sufficiently to be considered worth storing.
    uint64_t failed_page_compression_attempts;

    // Number of times pages have been decompressed.
    uint64_t total_page_decompressions;

    // Number of times a page was removed from storage without needing to be
    // decompressed. An example that would cause this is a VMO being destroyed.
    uint64_t compressed_page_evictions;

    // How many pages compressed due to the page being inactive, but without
    // there being memory pressure.
    uint64_t eager_page_compressions;

    // How many pages compressed due to general memory pressure. This excludes pages
    // compressed due to critical memory pressure.
    uint64_t memory_pressure_page_compressions;

    // How many pages compressed due to attempting to avoid OOM or near OOM
    // scenarios.
    uint64_t critical_memory_page_compressions;

    // The nanoseconds in the base unit of time for
    // |pages_decompressed_within_log_time|.
    uint64_t pages_decompressed_unit_ns;

    // How long pages spent compressed before being decompressed, grouped in log
    // buckets. Pages that got evicted, and hence were not decompressed, are not
    // counted here. Buckets are in |pages_decompressed_unit_ns| and round up
    // such that:
    // 0: Pages decompressed in <1 unit
    // 1: Pages decompressed between 1 and 2 units
    // 2: Pages decompressed between 2 and 4 units
    // ...
    // 7: Pages decompressed between 64 and 128 units
    // How many pages are held compressed for longer than 128 units can be
    // inferred by subtracting from |total_page_decompressions|.
    uint64_t pages_decompressed_within_log_time[8];
} zx_info_kmem_stats_compression_t;

ZX_INFO_RESOURCE

handle 類型:Resource

buffer 類型:zx_info_resource_t[1]

透過控制代碼傳回資源物件的相關資訊。

typedef struct zx_info_resource {
    // The resource kind; resource object kinds are described in resource.md
    uint32_t kind;
    // Resource's creation flags
    uint32_t flags;
    // Resource's base value (inclusive)
    uint64_t base;
    // Resource's length value
    size_t size;
    char name[ZX_MAX_NAME_LEN];
} zx_info_resource_t;

資源種類

  • ZX_RSRC_KIND_ROOT
  • ZX_RSRC_KIND_MMIO
  • ZX_RSRC_KIND_IOPORT
  • ZX_RSRC_KIND_IRQ
  • ZX_RSRC_KIND_SMC
  • ZX_RSRC_KIND_SYSTEM

ZX_INFO_BTI

handle 類型:Bus Transaction Initiator

buffer 類型:zx_info_bti_t[1]

typedef struct zx_info_bti {
    // zx_bti_pin will always be able to return addresses that are contiguous for at
    // least this many bytes. E.g. if this returns 1MB, then a call to
    // zx_bti_pin() with a size of 2MB will return at most two physically-contiguous runs.
    // If the size were 2.5MB, it will return at most three physically-contiguous runs.
    uint64_t minimum_contiguity;

    // The number of bytes in the device's address space (UINT64_MAX if 2^64).
    uint64_t aspace_size;

    // The count of the pinned memory object tokens. Requesting this count is
    // racy, so this should only be used for informative reasons.
    uint64_t pmo_count;

    // The count of the quarantined pinned memory object tokens. Requesting this count is
    // racy, so this should only be used for informative reasons.
    uint64_t quarantine_count;
} zx_info_bti_t;

主題 ZX_INFO_IOB

handle 類型:IOBuffer

buffer 類型:zx_info_iob_t[1]

傳回整個 IOB 執行個體的相關資訊。

typedef struct zx_info_iob {
  // The value of the *options* parameter passed to `zx_iob_create`.
  uint64_t options;
  // The number of regions in the IOB.
  uint32_t region_count;
  // Reserved for future extensions.
  uint8_t padding[4];
} zx_info_iob_t;

主題 ZX_INFO_IOB_REGIONS

zx_iob_region_info_t 陣列的形式傳回 IOB 每個區域的相關資訊

handle 類型:IOBuffer

buffer 類型:zx_iob_region_info_t[n]

struct zx_iob_region_info_t { // 區域說明,可能已變更存取位元。 zx_iob_region_t 區域; /// 基礎記憶體物件的 koid。 zx_koid_t koid; };

系統會替換存取修飾符位元,讓 Ep0 存取位元會反映 對進行查詢的端點存取,Ep1 位元則會反映 因此能夠判斷是對其他端點的存取權 本機和遠端控制代碼的一環 以及第 1 季的第 1 集

權限

如果 topicZX_INFO_PROCESS,則 handle 必須是 ZX_OBJ_TYPE_PROCESS 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_JOB,則 handle 必須是 ZX_OBJ_TYPE_JOB 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_PROCESS_THREADS,則 handle 必須是 ZX_OBJ_TYPE_PROCESS 類型且包含 ZX_RIGHT_ENUMERATE

如果 topicZX_INFO_JOB_CHILDREN,則 handle 必須是 ZX_OBJ_TYPE_JOB 類型且包含 ZX_RIGHT_ENUMERATE

如果 topicZX_INFO_JOB_PROCESSES,則 handle 必須是 ZX_OBJ_TYPE_JOB 類型且包含 ZX_RIGHT_ENUMERATE

如果 topicZX_INFO_THREAD,則 handle 必須是 ZX_OBJ_TYPE_THREAD 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_THREAD_EXCEPTION_REPORT,則 handle 必須是 ZX_OBJ_TYPE_THREAD 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_THREAD_STATS,則 handle 必須是 ZX_OBJ_TYPE_THREAD 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_TASK_STATS,則 handle 必須是 ZX_OBJ_TYPE_PROCESS 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_PROCESS_MAPS,則 handle 必須是 ZX_OBJ_TYPE_PROCESS 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_PROCESS_VMOS,則 handle 必須是 ZX_OBJ_TYPE_PROCESS 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_VMO,則 handle 必須是 ZX_OBJ_TYPE_VMO 類型。

如果 topicZX_INFO_VMAR,則 handle 必須是 ZX_OBJ_TYPE_VMAR 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_VMAR_MAPS,則 handle 必須是 ZX_OBJ_TYPE_VMAR 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_GUEST_STATS,則 handle 必須具備基本 ZX_RSRC_SYSTEM_INFO_BASE 的資源類型 ZX_RSRC_KIND_SYSTEM

如果 topicZX_INFO_CPU_STATS,則 handle 必須具備基本 ZX_RSRC_SYSTEM_INFO_BASE 的資源類型 ZX_RSRC_KIND_SYSTEM

如果 topicZX_INFO_KMEM_STATS,則 handle 必須具備基本 ZX_RSRC_SYSTEM_INFO_BASE 的資源類型 ZX_RSRC_KIND_SYSTEM

如果 topicZX_INFO_KMEM_STATS_EXTENDED,則 handle 必須具備基本 ZX_RSRC_SYSTEM_INFO_BASE 的資源類型 ZX_RSRC_KIND_SYSTEM

如果 topicZX_INFO_RESOURCE,則 handle 必須是 ZX_OBJ_TYPE_RESOURCE 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_HANDLE_COUNT,則 handle 必須有 ZX_RIGHT_INSPECT

如果 topicZX_INFO_BTI,則 handle 必須是 ZX_OBJ_TYPE_BTI 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_PROCESS_HANDLE_STATS,則 handle 必須是 ZX_OBJ_TYPE_PROCESS 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_SOCKET,則 handle 必須是 ZX_OBJ_TYPE_SOCKET 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_MSI,則 handle 必須是 ZX_OBJ_TYPE_MSI 類型且包含 ZX_RIGHT_INSPECT

如果 topicZX_INFO_TASK_RUNTIME,則 handle 必須是 ZX_OBJ_TYPE_THREADZX_OBJ_TYPE_PROCESSZX_OBJ_TYPE_JOB 類型,且具有 ZX_RIGHT_INSPECT

傳回值

zx_object_get_info() 會在成功時傳回 ZX_OK。故障時, 會傳回負錯誤值。

錯誤

ZX_ERR_BAD_HANDLE 帳號代碼不是有效的帳號代碼。

ZX_ERR_WRONG_TYPE 帳號代碼不適用於主題的類型

ZX_ERR_ACCESS_DENIED:如果帳號代碼沒有 作業。

ZX_ERR_INVALID_ARGS bufferactualavail 是無效的指標。

ZX_ERR_NO_MEMORY 因記憶體不足而失敗。無論如何 處理此 (異常) 錯誤。在日後的版本中,這項錯誤不會 才能避免這類問題再次發生

ZX_ERR_BUFFER_TOO_SMALL topic 會傳回固定數量的記錄,但 提供的緩衝區空間不足,無法容納這些記錄。

ZX_ERR_NOT_SUPPORTED主題不存在。

範例

bool is_handle_valid(zx_handle_t handle) {
    return zx_object_get_info(
        handle, ZX_INFO_HANDLE_VALID, NULL, 0, NULL, NULL) == ZX_OK;
}

zx_koid_t get_object_koid(zx_handle_t handle) {
    zx_info_handle_basic_t info;
    if (zx_object_get_info(handle, ZX_INFO_HANDLE_BASIC,
                           &info, sizeof(info), NULL, NULL) != ZX_OK) {
        return 0;
    }
    return info.koid;
}

void examine_threads(zx_handle_t proc) {
    zx_koid_t threads[128];
    size_t count, avail;

    if (zx_object_get_info(proc, ZX_INFO_PROCESS_THREADS, threads,
                           sizeof(threads), &count, &avail) != ZX_OK) {
        // Error!
    } else {
        if (avail > count) {
            // More threads than space in array;
            // could call again with larger array.
        }
        for (size_t n = 0; n < count; n++) {
            do_something(thread[n]);
        }
    }
}

另請參閱