摘要
分配新的子區域。
宣告
#include <zircon/syscalls.h>
zx_status_t zx_vmar_allocate(zx_handle_t parent_vmar,
zx_vm_option_t options,
size_t offset,
size_t size,
zx_handle_t* child_vmar,
zx_vaddr_t* child_addr);
說明
在 parent_vmar 指定的範圍內建立新的 VMAR。
options 是位元向量，包含下列一或多個項目：
ZX_VM_COMPACT向核心指示，在新建的子區域中配置和對應應保持近距離。請參閱下方的「NOTES」一節來討論。ZX_VM_SPECIFIC請使用 offset 來放置對應；如果 parent_vmar 沒有ZX_VM_CAN_MAP_SPECIFIC權限，則使用無效設定。offset 是相對於父項區域基本地址的偏移量。指定與其他 VMAR 或對應重疊的位址範圍將會導致錯誤。ZX_VM_OFFSET_IS_UPPER_LIMIT將 偏移 解讀為上限，以限制核心選取偏移量，如果 parent_vmar 沒有ZX_VM_CAN_MAP_SPECIFIC權限，則無效。產生的對應會有偏移值 + size 為 <= offset。如果使用ZX_VM_SPECIFIC，則無法指定這個選項。ZX_VM_CAN_MAP_SPECIFIC新的 VMAR 可使用ZX_VM_SPECIFIC建立子區域/對應。如果父項沒有ZX_VM_CAN_MAP_SPECIFIC權限，則「並非」錯誤。ZX_VM_CAN_MAP_READ新的 VMAR 可包含可讀取的對應關係。如果上層沒有ZX_VM_CAN_MAP_READ權限，則會導致錯誤。ZX_VM_CAN_MAP_WRITE新的 VMAR 可包含可寫入的對應關係。如果上層沒有ZX_VM_CAN_MAP_WRITE權限，則會導致錯誤。ZX_VM_CAN_MAP_EXECUTE新的 VMAR 可包含可執行的對應。如果上層沒有ZX_VM_CAN_MAP_EXECUTE權限，則會導致錯誤。
如果 options 未設定 ZX_VM_SPECIFIC 或 ZX_VM_OFFSET_IS_UPPER_LIMIT，offset 必須為 0。
此外，還可以新增以下二次方對齊旗標：
ZX_VM_ALIGN_1KB會將 child_addr 的值調整為 2 的次方至少 1,000 個位元組。ZX_VM_ALIGN_2KB會將 child_addr 的乘冪調整為至少 2,000 個位元組。ZX_VM_ALIGN_4KB會將 child_addr 調整為 2 的次方，至少為 4K 個位元組。ZX_VM_ALIGN_8KB會將 child_addr 的值調整為 8 千位元組的 2 乘冪。
直到
ZX_VM_ALIGN_4GB會將 child_addr 調整為 2 號至少 4G 位元組。
如果 parent_vmar 基本地址 + offset 不符合要求的值，則搭配 ZX_VM_SPECIFIC 使用 ZX_VM_ALIGN 標記時會失敗。
權限
如果 options 和 ZX_VM_CAN_MAP_READ，parent_vmar 必須是 ZX_OBJ_TYPE_VMAR 類型，且具有 ZX_RIGHT_READ。
如果 options 和 ZX_VM_CAN_MAP_WRITE，parent_vmar 必須是 ZX_OBJ_TYPE_VMAR 類型，且具有 ZX_RIGHT_WRITE。
如果 options 和 ZX_VM_CAN_MAP_EXECUTE，parent_vmar 必須是 ZX_OBJ_TYPE_VMAR 類型，且具有 ZX_RIGHT_EXECUTE。
傳回值
zx_vmar_allocate() 會傳回 ZX_OK、子區域的絕對基本位址 (透過 child_addr)，並在成功時傳回新子區域的控制代碼 (透過 child_vmar)。基本地址將以頁面對齊，且不為零。如果失敗，系統會傳回負值錯誤值。
錯誤
ZX_ERR_BAD_HANDLE parent_vmar 不是有效的帳號代碼。
ZX_ERR_WRONG_TYPE parent_vmar 並非 VMAR 控制代碼。
ZX_ERR_BAD_STATE parent_vmar 是指遭到刪除的 VMAR。
以下任一項目的 ZX_ERR_INVALID_ARGS：
- child_vmar 或 child_addr 無效，- 如未提供 ZX_VM_SPECIFIC 或 ZX_VM_OFFSET_IS_UPPER_LIMIT，offset 並非零。- ZX_VM_OFFSET_IS_UPPER_LIMIT 和 ZX_VM_SPECIFIC 一起指定。- offset 和 size 說明因超過區域邊界而導致無法滿足的配置 - offset 或 size 未對齊頁面，或 size 為 0。
ZX_ERR_NO_MEMORY可能原因如下：
- parent_vmar 中不提供要求大小的免費位址範圍。
- 系統記憶體資源不足。
ZX_ERR_ACCESS_DENIED 您的權限不足，無法執行要求的分配作業。
附註
經銷商據點
VMAR 佔用的位址空間將保持分配 (在其父項 VMAR 中)，直到呼叫 zx_vmar_destroy() 刪除 VMAR 為止。
請注意，只是關閉 VMAR 的控制代碼並不會取消分配 VMAR 佔用的位址空間。
COMPACT 旗標
核心會將這個標記解讀為要求，以減少配置中的支出。雖然這不需要降低分配位址的絕對熵，但分配作業之間的關聯可能極高。此情況可做出取捨，如果開發人員願意讓某些地址更具關聯性，開發人員可以盡量增加配置位置並減少所需的頁面資料表數量。