docs/reference/syscalls/vmo_set_cache_policy.md

<!-- Generated by zircon/scripts/update-docs-from-fidl, do not edit! -->
# zx_vmo_set_cache_policy

## SUMMARY

Set the caching policy for pages held by a VMO.

## Declaration

```c
#include <zircon/syscalls.h>

zx_status_t zx_vmo_set_cache_policy(zx_handle_t handle, uint32_t cache_policy);
```

## Description

`zx_vmo_set_cache_policy()` sets caching policy for a [virtual memory
object](/docs/reference/kernel_objects/vm_object.md) (VMO). Generally used on VMOs
that point directly at physical memory. Such VMOs are generally only handed to
userspace via bus protocol interfaces, so this syscall will typically only be
used by drivers dealing with device memory. This call can also be used on a
regular memory backed VMO with similar limitations and uses.

A handle must have the **ZX_RIGHT_MAP** right for this call to be
permitted. Additionally, the VMO must not presently be mapped by any process,
have any children, be a child itself, or have any pinned pages. Having committed
pages is only allowed if transitioning from a cached state, and the pages will be
cleaned and invalidated.

*cache_policy* cache flags to use:

  - **ZX_CACHE_POLICY_CACHED** - Use hardware caching. On Aarch64 this corresponds to the Normal
    Memory, Outer Write-back non-transient Read and Write allocate, Inner Write-back non-transient
    Read and Write allocate memory attributes

  - **ZX_CACHE_POLICY_UNCACHED** - Disable caching. On Aarch64 this corresponds to the Device-nGnRnE
    memory attributes.

  - **ZX_CACHE_POLICY_UNCACHED_DEVICE** - Disable cache and treat as device memory. This is
    architecture dependent and may be equivalent to **ZX_CACHE_POLICY_UNCACHED** on some
    architectures. On Aarch64 this corresponds to the Device-nGnRE memory attributes.

  - **ZX_CACHE_POLICY_WRITE_COMBINING** - Uncached with write combining. On Aarch64 this corresponds
    to the Normal memory, uncached memory attributes.


## Rights

*handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_MAP**.

## Return value

`zx_vmo_set_cache_policy()` returns **ZX_OK** on success. In the event of
failure, a negative error value is returned.

## Errors

**ZX_ERR_ACCESS_DENIED** Cache policy has been configured for this VMO already and
may not be changed, or *handle* lacks the **ZX_RIGHT_MAP** right.

**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.

**ZX_ERR_INVALID_ARGS** *cache_policy* contains flags outside of the ones listed
above, or *cache_policy* contains an invalid mix of cache policy flags.

**ZX_ERR_NOT_SUPPORTED** The VMO *handle* corresponds to is not one holding
physical memory.

**ZX_ERR_BAD_STATE** Cache policy cannot be changed because the VMO is presently
mapped, has children, is a child itself, has pinned pages, or has committed pages
and the VMO is currently not cached.

## See also

 - [`zx_vmo_create()`]
 - [`zx_vmo_get_size()`]
 - [`zx_vmo_op_range()`]
 - [`zx_vmo_read()`]
 - [`zx_vmo_set_size()`]
 - [`zx_vmo_write()`]

[`zx_vmo_create()`]: vmo_create.md
[`zx_vmo_get_size()`]: vmo_get_size.md
[`zx_vmo_op_range()`]: vmo_op_range.md
[`zx_vmo_read()`]: vmo_read.md
[`zx_vmo_set_size()`]: vmo_set_size.md
[`zx_vmo_write()`]: vmo_write.md