总结
分配新的子区域。
声明
#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：一条提示，旨在提示内核，新创建的子区域中的分配和映射应保持紧密相关。请参阅下文的“备注”部分进行讨论。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权限，则无效。生成的映射的 offset + 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 对齐为至少 1K 字节的 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_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 内），直到 VMAR 通过调用 zx_vmar_destroy() 销毁。
请注意，仅关闭 VMAR 的句柄并不会取消分配 VMAR 占用的地址空间。
COMPACT 标志
内核将此标记解读为请求减少分配中的无序扩张。 虽然这不需要降低已分配地址的绝对熵，但分配之间可能存在非常高的相关性。如果开发者愿意让某些地址更具相关性，就可以进行这种权衡，以增加分配位置并减少所需的页面表数量。