Google is committed to advancing racial equity for Black communities. See how.

zx_pager_create_vmo

NAME

Create a pager owned vmo.

SYNOPSIS

#include <zircon/syscalls.h>

zx_status_t zx_pager_create_vmo(zx_handle_t pager,
                                uint32_t options,
                                zx_handle_t port,
                                uint64_t key,
                                uint64_t size,
                                zx_handle_t* out);

DESCRIPTION

Creates a VMO owned by a pager object. size will be rounded up to the next page size boundary, and options must be zero or ZX_VMO_RESIZABLE.

On success, the returned vmo has the same rights as a vmo created with zx_vmo_create(), as well as having the same behavior with respect to ZX_VMO_ZERO_CHILDREN. Syscalls which operate on VMOs require an explicit flag to allow blocking IPC to the userspace pager service; beyond this, whether or not a VMO is owned by a pager does not affect the semantics of syscalls.

TODO(stevend): Update differences after updates to cloning and decommit

Page requests will be delivered to port when certain conditions are met. Those packets will have type set to ZX_PKT_TYPE_PAGE_REQUEST and key set to the value provided to zx_pager_create_vmo(). The packet's union is of type zx_packet_page_request_t:

typedef struct zx_packet_page_request {
    uint16_t command;
    uint16_t flags;
    uint32_t reserved0;
    uint64_t offset;
    uint64_t length;
    uint64_t reserved1;
} zx_packet_page_request_t;

offset and length are always page-aligned. The value of any bits in flags for which flags are not defined is unspecified - currently no flags are defined. The trigger and meaning of the packet depends on command, which can take one of the following values:

ZX_PAGER_VMO_READ: Sent when an application accesses a non-resident page in a pager's VMO. The pager service should populate the range [offset, offset + length) in the registered vmo with zx_pager_supply_pages(). Supplying pages is an implicit positive acknowledgement of the request.

ZX_PAGER_VMO_COMPLETE: Sent when no more pager requests will be sent for the corresponding VMO, either because of zx_pager_detach_vmo() or because no references to the VMO remain.

If pager is closed, then no more packets will be delivered to port (including no ZX_PAGER_VMO_COMPLETE message). Furthermore, all future accesses will behave as if zx_pager_detach_vmo() had been called.

RIGHTS

pager must be of type ZX_OBJ_TYPE_PAGER.

port must be of type ZX_OBJ_TYPE_PORT and have ZX_RIGHT_WRITE.

RETURN VALUE

zx_pager_create_vmo() returns ZX_OK on success, or one of the following error codes on failure.

ERRORS

ZX_ERR_INVALID_ARGS out is an invalid pointer or NULL, or options is any value other than 0 or ZX_VMO_RESIZABLE.

ZX_ERR_BAD_HANDLE pager or port is not a valid handle.

ZX_ERR_ACCESS_DENIED port does not have ZX_RIGHT_WRITE.

ZX_ERR_WRONG_TYPE pager is not a pager handle or port is not a port handle.

ZX_ERR_OUT_OF_RANGE The requested size is larger than the maximum vmo size.

ZX_ERR_NO_MEMORY Failure due to lack of memory.

SEE ALSO