zx_vmo_transfer_data

SUMMARY

Moves data into a VMO.

Declaration

#include <zircon/syscalls.h>

zx_status_t zx_vmo_transfer_data(zx_vmo_t dst_vmo,
                                 uint32_t options,
                                 uint64_t offset,
                                 uint64_t length,
                                 zx_vmo_t src_vmo,
                                 uint64_t src_offset);

Description

Moves the pages in [*src_offset*, *src_offset* + *length*) from src_vmo to [*offset*, *offset* + *length*) in dst_vmo. It is functionally equivalent to a memmove from src_vmo to dst_vmo followed by a decommit of the associated pages in src_vmo. However, the mechanism by which this is achieved is different; the backing pages are actually moved between VMOs instead of copying data. This allows for much better performance. Despite this different mechanism, this syscall presents the same semantics as memmove, in that providing overlapping source and destination regions is supported.

The options field must currently be set to 0.

Rights

dst_vmo must be of type ZX_OBJ_TYPE_VMO. This handle must have ZX_RIGHT_WRITE.

src_vmo must be of type ZX_OBJ_TYPE_VMO. This handle must have ZX_RIGHT_READ and ZX_RIGHT_WRITE.

Return value

zx_vmo_transfer_data() returns ZX_OK on success. In the event of failure, a negative error value is returned (as described below). If the transfer fails, then any number of pages in src_vmo may have been moved to dst_vmo. We make no guarantees as to exactly how much data was moved. However, we can guarantee that the call will succeed if the following conditions are met:

  1. None of the conditions that would result in the errors listed below are met.
  2. The src_vmo and dst_vmo are not modified by any other threads while this operation is running.

A "modification" in this context refers to a write/resize/pin on either the VMO directly or on a reference to the VMO (e.g. slices, reference children, etc.). Modifying a parent, child, or sibling of any kind of snapshot should not result in any error, although depending on the snapshot you may get write tearing. Write tearing could occur if you manipulate the parent of a SNAPSHOT_AT_LEAST_ON_WRITE VMO as the actual transfer has no promised atomicity. Note that in the case of transferring pages from a SNAPSHOT child we may need to perform copies, i.e. allocate new pages, if that particular page has not yet been copy-on-written.

Errors

ZX_ERR_BAD_HANDLE dst_vmo or src_vmo is not a valid VMO handle.

ZX_ERR_INVALID_ARGS offset, length, or src_offset is not page aligned, or options is nonzero.

ZX_ERR_ACCESS_DENIED src_vmo does not have ZX_RIGHT_WRITE or ZX_RIGHT_READ, or dst_vmo does not have ZX_RIGHT_WRITE.

ZX_ERR_BAD_STATE Pages in the specified range in src_vmo or dst_vmo are pinned.

ZX_ERR_NOT_SUPPORTED Either src_vmo or dst_vmo is physical, contiguous, or pager-backed.

ZX_ERR_OUT_OF_RANGE The specified range in dst_vmo or src_vmo is invalid.

ZX_ERR_NO_MEMORY Failure due to lack of memory.

See also