zx_vmo_clone

英文原文快照

名称

vmo_clone —— 创建VM对象的副本

概要

  1. #include <zircon/syscalls.h>
  3. zx_status_t zx_vmo_clone(zx_handle_t handle, uint32_t options, uint64_t offset, uint64_t size, zx_handle_t* out);

描述

vmo_clone() 的功能是创建一个新的虚拟内存对象（VMO），用于克隆现有vmo的内存区域。

调用成功则返回一个句柄，表示具有所请求内存大小的对象。

options必须包含ZX_VMO_CLONE_COPY_ON_WRITE选项，以及零个或多个标志位以控制克隆对象的创建。

有效的标志位包括：

  • ZX_VMO_CLONE_COPY_ON_WRITE —— 创建写时复制（Copy-on-write）的副本。 除了对副本的任何写操作将在写入位置的偏移量处引入页面的新副本之外，克隆的vmo将以与原始VMO相同的方式运行。 vmo副本中的新页面是原页面的副本，但已与父页面分离。 任何来自父VMO大小范围之外的读取操作都将返回零，并且写入操作将分配新的零填充页面。 有关与副本交互的VMO系统调用的详细信息，请参阅下面的注释部分。
  • ZX_VMO_CLONE_NON_RESIZEABLE —— 创建不可调整大小的VMO副本。

offset大小必须是页面对齐的。 offset + size不得超过64位无符号值的范围。

偏移量和大小都可以超出原始VMO的大小。

VMO将向上舍入到下一页面边界的大小。

默认情况下，副本的句柄的权限与原始句柄权限相同，但有一些例外。 有关每项权限的详细信息，请参阅vmo_create。

如果options为ZX_VMO_CLONE_COPY_ON_WRITE，则会添加以下权限到句柄上：

  • ZX_RIGHT_WRITE

注释

克隆VMO会导致现有（原始）VMO的ZX_VMO_ZERO_CHILDREN信号变成非活跃状态。 只有当最后一个副本被销毁并且没有这些副本到地址空间的映射时，ZX_VMO_ZERO_CHILDREN才会再次激活。

ZX_VMO_CLONE_COPY_ON_WRITE

此模式生成的VMO将通过以下方式与VMO系统调用进行交互：

  • 副本上的vmo_op_range() 的DECOMMIT和COMMIT模式只会影响分配给副本的页面，而不会影响其父节点。
  • 如果副本中的页面被解除提交（例如使用vmo_op_range() 操作），则父页面将再次可见，并且仍具有写时复制语义。
  • 如果使用vmo_op_range() 的COMMIT模式将页面提交到副本上，则新页面将具有与父对应页面相同的内容（如果不存在此页面，则使用零填充）。
  • 如果使用vmo_op_range() 的LOOKUP模式，则父节点中副本未修改的页面将仍然可见。

权限

TODO(ZX-2399)

返回值

vmo_clone() 调用成功则返回ZX_OK，如果发生错误，则返回负的错误码。

错误码

ZX_ERR_WRONG_TYPE：输入句柄不是VMO类型。

ZX_ERR_ACCESS_DENIED：输入句柄没有足够的权限。

ZX_ERR_INVALID_ARGS：out是无效指针或为NULL；或偏移量不是页面对齐的。

ZX_ERR_OUT_OF_RANGE：offset + size太大超出了范围。

ZX_ERR_NO_MEMORY：由于内存不足导致的失败。 而用户空间无法处理这个（不太可能发生的）错误。 在将来的构建版本中，将不再出现此错误。

另见

vmo_create, vmo_read, vmo_write, vmo_set_size, vmo_get_size, vmo_op_range, vmar_map.