zx_vmar_assign

摘要

分配新的子區域。

宣告

#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 內建立新的 VMAR。

options 是位元向量，包含下列一或多個項目：

  • ZX_VM_COMPACT 提示核心，新建立子區域內的分配和對應應保持緊密。 請參閱下方的「附註」一節。
  • ZX_VM_SPECIFIC 使用 offset 放置對應，如果 parent_vmar 沒有 ZX_VM_CAN_MAP_SPECIFIC 權限，則無效。 offset 是相對於父項區域基底位址的偏移量。 指定與其他 VMAR 或對應項目重疊的位址範圍是錯誤行為。
  • ZX_VM_OFFSET_IS_UPPER_LIMIT 將「offset」解讀為上限，藉此限制核心選取的偏移量。如果「parent_vmar」沒有 ZX_VM_CAN_MAP_SPECIFIC 權限，這個值就會無效。產生的對應項目會包含偏移值 + 大小，且該值 <= 偏移值。如果使用 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。

此外，您還可以新增下列 2 的冪對齊旗標：

  • ZX_VM_ALIGN_1KB 會將 child_addr 對齊至至少 1 KB 的 2 的乘方。
  • ZX_VM_ALIGN_2KB 會將 child_addr 對齊至至少 2K 位元組的 2 的乘方。
  • ZX_VM_ALIGN_4KB 會將 child_addr 對齊至至少 4K 位元組的 2 的冪。
  • ZX_VM_ALIGN_8KB 會將 child_addr 對齊至至少 8K 位元組的 2 的乘方。

並持續到

  • ZX_VM_ALIGN_4GB 會將 child_addr 對齊至少 4G 位元組的 2 的乘方。

如果 parent_vmar 基本位址 + offset 未與要求的值對齊，使用 ZX_VM_ALIGN 旗標搭配 ZX_VM_SPECIFIC 就會失敗。

權限

如果 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 記憶體不足，因此失敗。 使用者空間無法妥善處理這個 (不太可能發生的) 錯誤。 日後的版本將不會再發生這個錯誤。

ZX_ERR_NO_RESOURCES 如果 VMAR 中找不到可分配區域的位置。

ZX_ERR_ACCESS_DENIED 權限不足，無法進行要求的分配。

附註

解除分配

在呼叫 zx_vmar_destroy() 毀損 VMAR 前，VMAR 占用的位址空間會持續分配 (位於其父項 VMAR 內)。

請注意，單純關閉 VMAR 的控制代碼不會解除分配 VMAR 占用的位址空間。

COMPACT 旗標

核心會將這個旗標解讀為要求減少分配作業的蔓延情況。雖然這不代表必須減少所分配位址的絕對熵，但分配作業之間可能存在高度關聯性。如果開發人員願意讓特定位址更具相關性，就可以做出這項取捨，以提高分配作業的區域性，並減少必要的頁面表格數量。

另請參閱