1# zx_vmo_set_cache_policy
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7vmo_set_cache_policy - set the caching policy for pages held by a VMO.
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_vmo_set_cache_policy(zx_handle_t handle, uint32_t cache_policy);
17```
18
19## DESCRIPTION
20
21`zx_vmo_set_cache_policy()` sets caching policy for a VMO. Generally used on VMOs
22that point directly at physical memory. Such VMOs are generally only handed to
23userspace via bus protocol interfaces, so this syscall will typically only be
24used by drivers dealing with device memory. This call can also be used on a
25regular memory backed VMO with similar limitations and uses.
26
27A handle must have the **ZX_RIGHT_MAP** right for this call to be
28permitted. Additionally, the VMO must not presently be mapped by any process,
29be cloned, be a clone itself, or have any memory committed.
30
31*cache_policy* cache flags to use:
32
33**ZX_CACHE_POLICY_CACHED** - Use hardware caching.
34
35**ZX_CACHE_POLICY_UNCACHED** - Disable caching.
36
37**ZX_CACHE_POLICY_UNCACHED_DEVICE** - Disable cache and treat as device memory.
38This is architecture dependent and may be equivalent to
39**ZX_CACHE_POLICY_UNCACHED** on some architectures.
40
41**ZX_CACHE_POLICY_WRITE_COMBINING** - Uncached with write combining.
42
43## RIGHTS
44
45<!-- Updated by update-docs-from-abigen, do not edit. -->
46
47*handle* must be of type **ZX_OBJ_TYPE_VMO** and have **ZX_RIGHT_MAP**.
48
49## RETURN VALUE
50
51`zx_vmo_set_cache_policy()` returns **ZX_OK** on success. In the event of
52failure, a negative error value is returned.
53
54## ERRORS
55
56**ZX_ERR_ACCESS_DENIED** Cache policy has been configured for this VMO already and
57may not be changed, or *handle* lacks the **ZX_RIGHT_MAP** right.
58
59**ZX_ERR_BAD_HANDLE** *handle* is not a valid handle.
60
61**ZX_ERR_INVALID_ARGS** *cache_policy* contains flags outside of the ones listed
62above, or *cache_policy* contains an invalid mix of cache policy flags.
63
64**ZX_ERR_NOT_SUPPORTED** The VMO *handle* corresponds to is not one holding
65physical memory.
66
67**ZX_ERR_BAD_STATE** Cache policy cannot be changed because the VMO is presently
68mapped, cloned, a clone itself, or have any memory committed.
69
70## SEE ALSO
71
72 - [`zx_vmo_create()`]
73 - [`zx_vmo_get_size()`]
74 - [`zx_vmo_op_range()`]
75 - [`zx_vmo_read()`]
76 - [`zx_vmo_set_size()`]
77 - [`zx_vmo_write()`]
78
79<!-- References updated by update-docs-from-abigen, do not edit. -->
80
81[`zx_vmo_create()`]: vmo_create.md
82[`zx_vmo_get_size()`]: vmo_get_size.md
83[`zx_vmo_op_range()`]: vmo_op_range.md
84[`zx_vmo_read()`]: vmo_read.md
85[`zx_vmo_set_size()`]: vmo_set_size.md
86[`zx_vmo_write()`]: vmo_write.md
87