zx_resource_create

摘要

建立資源物件。

宣告

#include <zircon/syscalls.h>

zx_status_t zx_resource_create(zx_handle_t parent_rsrc,
                               uint32_t options,
                               uint64_t base,
                               size_t size,
                               const char* name,
                               size_t name_size,
                               zx_handle_t* resource_out);

說明

zx_resource_create() 會建立資源物件，供其他 DDK 系統呼叫使用。資源通常會發給公車司機，司機很少需要使用驅動程式庫通訊協定直接與資源互動。資源物件會授予存取權，存取從 base 開始的位址空間範圍，直到 base + size (不含) 為止。kind 有特殊值： ZX_RSRC_KIND_SYSTEM。系統資源是範圍資源，屬於多項資源的父項，所有資源的大小都是 1，用於系統呼叫的權限檢查。

parent_rsrc 必須是與所要求 kind 相符的資源控制代碼，且範圍內包含 [base, base+size]。

options 必須指定要建立的資源類型，且可能包含選用旗標。有效的資源種類包括 ZX_RSRC_KIND_MMIO、ZX_RSRC_KIND_IRQ、ZX_RSRC_KIND_IOPORT (僅限 x86)、ZX_RSRC_KIND_SMC (僅限 ARM) 和 ZX_RSRC_KIND_SYSTEM。ZX_RSRC_KIND_SYSTEM 的有效底座為 ZX_RSRC_SYSTEM_HYPERVISOR_BASE、ZX_RSRC_SYSTEM_VMEX_BASE、ZX_RSRC_SYSTEM_DEBUG_BASE、ZX_RSRC_SYSTEM_INFO_BASE、ZX_RSRC_SYSTEM_CPU_BASE、ZX_RSRC_SYSTEM_POWER_BASE、ZX_RSRC_SYSTEM_MEXEC_BASE、ZX_RSRC_SYSTEM_ENERGY_INFO_BASE、ZX_RSRC_SYSTEM_IOMMU_BASE、ZX_RSRC_SYSTEM_PROFILE_BASE、/ ZX_RSRC_SYSTEM_MSI_BASE、ZX_RSRC_SYSTEM_DEBUGLOG_BASE 和 ZX_RSRC_SYSTEM_STALL_BASE。這些全都具有大小 1。

ZX_RSRC_FLAG_EXCLUSIVE 是選用旗標。如果提供 ZX_RSRC_FLAG_EXCLUSIVE，系統呼叫會嘗試專屬保留所要求的位址空間區域，只要該區域存在，其他資源建立作業就不會與其重疊。

name 和 name_size 為選用屬性，且會截斷至 ZX_MAX_NAME_LENGTH - 1。 這個名稱僅供偵錯 / 工具使用，核心不會使用。

成功時，系統會在 resource_out 中傳回有效的資源控制代碼。

系統預設會為帳號代碼設定下列權利：

  • ZX_RIGHT_DUPLICATE - 控制代碼可能會重複。

  • ZX_RIGHT_TRANSFER - 控制代碼可能會轉移至其他程序。

  • ZX_RIGHT_WRITE - Checked by zx_resource_create() itself.

  • ZX_RIGHT_INSPECT - May inspect the object with zx_object_get_info().

  • ZX_RIGHT_GET_PROPERTY - 可能會使用 zx_object_get_property() 取得其屬性。

  • ZX_RIGHT_SET_PROPERTY - May set its properties using zx_object_set_property().

傳回值

zx_resource_create() 會在成功時傳回 ZX_OK。如果失敗，系統會傳回負數錯誤值。

權限

parent_rsrc 必須是 ZX_OBJ_TYPE_RESOURCE 類型，且具有 ZX_RIGHT_WRITE。

錯誤

ZX_ERR_BAD_HANDLE parent_rsrc 控制代碼無效。

ZX_ERR_WRONG_TYPE parent_rsrc 控制代碼不是資源控制代碼。

ZX_ERR_ACCESS_DENIED parent_rsrc 控制代碼不是 kind 的資源。

ZX_ERR_INVALID_ARGS options 包含無效的種類或旗標組合，或 name 是無效的指標。

ZX_ERR_NOT_FOUND 找不到合適的資源分配方式。如果位址範圍無效、範圍已由專屬資源擁有，或是存在一般資源，而呼叫者嘗試在相同範圍內建立專屬資源，就會發生這種情況。

ZX_ERR_NO_MEMORY 記憶體不足，因此失敗。使用者空間無法妥善處理這個 (不太可能發生的) 錯誤。日後建構版本將不會再發生這個錯誤。

另請參閱