blob: da62b4458aba351da71ca47a3d908bf64575d430 [file] [log] [blame] [view]
# zx_vmo_op_range
## NAME
<!-- Updated by update-docs-from-fidl, do not edit. -->
Perform an operation on a range of a VMO.
## SYNOPSIS
<!-- Updated by update-docs-from-fidl, do not edit. -->
```c
#include <zircon/syscalls.h>
zx_status_t zx_vmo_op_range(zx_handle_t handle,
uint32_t op,
uint64_t offset,
uint64_t size,
void* buffer,
size_t buffer_size);
```
## DESCRIPTION
`zx_vmo_op_range()` performs cache and memory operations against pages held by the VMO.
*offset* byte offset specifying the starting location for *op* in the VMO's held memory.
*size* length, in bytes, to perform the operation on.
*op* the operation to perform:
*buffer* and *buffer_size* are currently unused.
**ZX_VMO_OP_COMMIT** - Commit *size* bytes worth of pages starting at byte *offset* for the VMO.
More information can be found in the [vm object documentation](/docs/reference/kernel_objects/vm_object.md).
Requires the **ZX_RIGHT_WRITE** right.
**ZX_VMO_OP_DECOMMIT** - Release a range of pages previously committed to the VMO from *offset*
to *offset*+*size*, which resets that range's bytes to 0. Requires the **ZX_RIGHT_WRITE** right.
This is only supported for vmos created from [`zx_vmo_create()`], which do not have non-slice
children, and for slice children of such vmos. Provided range must be page aligned.
**ZX_VMO_OP_ZERO** - Resets the range of bytes in the VMO from *offset* to *offset*+*size* to
0. This is semantically equivalent to writing 0's with
[`zx_vmo_write()`](/docs/reference/syscalls/vmo_write.md), except that it is able to be done more
efficiently and save memory by de-duping to shared zero pages. Requires the **ZX_RIGHT_WRITE** right.
**ZX_VMO_OP_LOCK** - Locks a range of pages in a discardable VMO, preventing them from being
discarded by the kernel. Guaranteed to succeed if the arguments are valid. *buffer* should point to
a `zx_vmo_lock_state_t` struct, and *buffer_size* should accommodate the struct. Returns information
about the locked and previously discarded ranges in *buffer*, so that clients can reinitialize
discarded contents if needed.
The entire VMO should be locked at once, so *offset* should be 0 and *size* should be the current
size of the VMO. Requires the **ZX_RIGHT_READ** or **ZX_RIGHT_WRITE** right. Note that locking
itself does not commit any pages in the VMO; it just marks the state of the VMO as “undiscardable”
by the kernel.
*buffer* should be a pointer of type `zx_info_lock_state_t`.
```
typedef struct zx_vmo_lock_state {
// |offset| and |size| track the locked range, and will be set to the |offset|
// and |size| arguments passed in if the ZX_VMO_OP_LOCK is successful.
uint64_t offset;
uint64_t size;
// |discarded_offset| and |discarded_size| track the discarded range prior to
// the lock operation. This is the maximal range within the locked range that
// contains discarded pages; not all pages within this range might have been
// discarded. Both |discarded_offset| and |discarded_size| will be set to 0 if
// the range was not discarded.
uint64_t discarded_offset;
uint64_t discarded_size;
} zx_vmo_lock_state_t;
```
**ZX_VMO_OP_TRY_LOCK** - Locks a range of pages in a discardable VMO, preventing them from being
discarded by the kernel. Will only succeed if the range has not already been discarded by the
kernel, and will fail with **ZX_ERR_UNAVAILABLE** otherwise. This operation is meant as a
lightweight alternative to **ZX_VMO_OP_LOCK** for trying to lock the VMO without having to set up
the *buffer* argument; it also affords clients the choice to not take any action following failure
to lock the VMO.
The entire VMO should be locked at once, so *offset* should be 0 and *size* should be the current
size of the VMO. Requires the **ZX_RIGHT_READ** or **ZX_RIGHT_WRITE** right. Note that locking
itself does not commit any pages in the VMO; it just marks the state of the VMO as “undiscardable”
by the kernel.
**ZX_VMO_OP_UNLOCK** - Unlocks a range of pages in a discardable VMO, indicating that the kernel is
free to discard them under memory pressure. The entire VMO should be unlocked at once, so *offset*
should be 0 and *size* should be the current size of the VMO. Requires the **ZX_RIGHT_READ** or
**ZX_RIGHT_WRITE** right.
**ZX_VMO_OP_CACHE_SYNC** - Performs a cache sync operation.
Requires the **ZX_RIGHT_READ** right.
**ZX_VMO_OP_CACHE_INVALIDATE** - Performs a cache invalidation operation.
Requires the **ZX_RIGHT_WRITE** right.
**ZX_VMO_OP_CACHE_CLEAN** - Performs a cache clean operation.
Requires the **ZX_RIGHT_READ** right.
**ZX_VMO_OP_CACHE_CLEAN_INVALIDATE** - Performs cache clean and invalidate operations together.
Requires the **ZX_RIGHT_READ** right.
## RIGHTS
<!-- Updated by update-docs-from-fidl, do not edit. -->
If *op* is **ZX_VMO_OP_COMMIT**, *handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_WRITE**.
If *op* is **ZX_VMO_OP_DECOMMIT**, *handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_WRITE**.
If *op* is **ZX_VMO_OP_CACHE_SYNC**, *handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_READ**.
If *op* is **ZX_VMO_OP_CACHE_INVALIDATE**, *handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_WRITE**.
If *op* is **ZX_VMO_OP_CACHE_CLEAN**, *handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_READ**.
If *op* is **ZX_VMO_OP_CACHE_CLEAN_INVALIDATE**, *handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_READ**.
## RETURN VALUE
`zx_vmo_op_range()` returns **ZX_OK** on success. In the event of failure, a negative error
value is returned.
## ERRORS
**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.
**ZX_ERR_OUT_OF_RANGE** An invalid memory range specified by *offset* and *size*.
**ZX_ERR_NO_MEMORY** Allocations to commit pages for **ZX_VMO_OP_COMMIT** or **ZX_VMO_OP_ZERO**
failed.
**ZX_ERR_WRONG_TYPE** *handle* is not a VMO handle.
**ZX_ERR_ACCESS_DENIED** *handle* does not have sufficient rights to perform the operation.
**ZX_ERR_INVALID_ARGS** *buffer* is an invalid pointer (if required by the operation), *op* is not
a valid operation, *size* is zero and *op* is a cache operation, or *op* was **ZX_VMO_OP_DECOMMIT**
and range was not page aligned.
**ZX_ERR_NOT_SUPPORTED** *op* was **ZX_VMO_OP_LOCK**, **ZX_VMO_OP_TRY_LOCK** or
**ZX_VMO_OP_UNLOCK** and the VMO is not discardable, or *op* was **ZX_VMO_OP_DECOMMIT** and the
underlying VMO does not allow decommiting.
**ZX_ERR_UNAVAILABLE** *op* was **ZX_VMO_OP_TRY_LOCK**, the VMO was discardable and the VMO has been
discarded by the kernel.
**ZX_ERR_BAD_STATE** *op* was **ZX_VMO_OP_COMMIT**, the VMO is backed by a pager and the pager or
the VMO is in a bad state preventing requested pages from being populated. *op* was
**ZX_VMO_OP_UNLOCK**, the VMO is discardable and the VMO was not previously locked.
**ZX_ERR_IO** *op* was **ZX_VMO_OP_COMMIT**, the VMO is backed by a pager and the pager encountered
an I/O error while committing the requested pages.
**ZX_ERR_IO_DATA_INTEGRITY** *op* was **ZX_VMO_OP_COMMIT**, the VMO is backed by a pager and the
contents that were read in by the pager for the pages being committed are corrupted.
## SEE ALSO
- [`zx_vmo_create()`]
- [`zx_vmo_create_child()`]
- [`zx_vmo_get_size()`]
- [`zx_vmo_read()`]
- [`zx_vmo_set_size()`]
- [`zx_vmo_write()`]
<!-- References updated by update-docs-from-fidl, do not edit. -->
[`zx_vmo_create()`]: vmo_create.md
[`zx_vmo_create_child()`]: vmo_create_child.md
[`zx_vmo_get_size()`]: vmo_get_size.md
[`zx_vmo_read()`]: vmo_read.md
[`zx_vmo_set_size()`]: vmo_set_size.md
[`zx_vmo_write()`]: vmo_write.md