摘要
對 VMO 的範圍執行作業。
宣告
#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);
說明
zx_vmo_op_range() 會對 虛擬記憶體物件 (VMO) 保留的頁面執行快取和記憶體作業。
offset：位元組偏移值，指定 VMO 所保留記憶體中 op 的起始位置。
size 長度 (以位元組為單位)，用於執行作業。
op：要執行的作業：
視 op 而定，可能需要或不需要 buffer 和 buffer_size，詳情請參閱下文。
ZX_VMO_OP_COMMIT - Commit size bytes worth of pages starting at byte offset for the VMO.
詳情請參閱 vm 物件說明文件。
需要 ZX_RIGHT_WRITE 權限。
ZX_VMO_OP_DECOMMIT - 從 offset 到 offset+size，釋放先前提交給 VMO 的一系列頁面，將該範圍的位元組重設為 0。需要 ZX_RIGHT_WRITE 權限。
這項功能僅適用於從 zx_vmo_create() 建立的 VMOS，這類 VMOS 沒有非切片子項，且適用於這類 VMOS 的切片子項。提供的範圍必須與頁面對齊。
ZX_VMO_OP_PREFETCH - Prefetch size bytes worth of pages starting at byte offset for the
VMO. 實際頁面可能會或可能不會提交，但範圍的未來讀取作業應具有類似的效能特徵，如同這項作業已由範圍內的讀取作業取代。需要 ZX_RIGHT_READ 權限。
ZX_VMO_OP_ZERO - 將 VMO 中從 offset 到 offset+size 的位元組範圍重設為 0。這在語意上等同於使用 zx_vmo_write() 寫入 0，但可更有效率地完成，並透過重複資料刪除至共用零頁面來節省記憶體。需要 ZX_RIGHT_WRITE 權限。
ZX_VMO_OP_LOCK - 鎖定以 ZX_VMO_DISCARDABLE 建立的 VMO 中的一系列頁面，防止核心捨棄這些頁面。如果引數有效，保證可成功鎖定 VMO 並傳回 ZX_OK。buffer 應指向 zx_vmo_lock_state_t 結構，而 buffer_size 應容納該結構。傳回 buffer 中已鎖定和先前捨棄的範圍相關資訊，以便用戶端視需要重新初始化捨棄的內容。
整個 VMO 應一次鎖定，因此 offset 應為 0，而 size 應為 VMO 的目前大小 (即 zx_vmo_get_size() 傳回的頁面對齊大小)。需要 ZX_RIGHT_READ 或 ZX_RIGHT_WRITE 權限。請注意，鎖定本身不會在 VMO 中提交任何頁面，只會由核心將 VMO 的狀態標示為「不可捨棄」。
buffer 應為 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 - 鎖定以 ZX_VMO_DISCARDABLE 建立的 VMO 中的一系列頁面，防止核心捨棄這些頁面。只有在核心尚未捨棄範圍的情況下才會成功，否則會失敗並傳回 ZX_ERR_UNAVAILABLE。這項作業是 ZX_VMO_OP_LOCK 的輕量替代方案，可嘗試鎖定 VMO，不必設定 buffer 引數。此外，如果 VMO 鎖定失敗，用戶端也可以選擇不採取任何行動；如要再次鎖定 VMO，用戶端必須使用 ZX_VMO_OP_LOCK。
整個 VMO 應一次鎖定，因此 offset 應為 0，而 size 應為 VMO 的目前大小 (即 zx_vmo_get_size() 傳回的頁面對齊大小)。需要 ZX_RIGHT_READ 或 ZX_RIGHT_WRITE 權限。請注意，鎖定本身不會在 VMO 中提交任何頁面，只會由核心將 VMO 的狀態標示為「不可捨棄」。
ZX_VMO_OP_UNLOCK - 解鎖以 ZX_VMO_DISCARDABLE 建立的 VMO 中的一系列頁面，表示核心可在記憶體壓力下捨棄這些頁面。尚未捨棄的已解鎖頁面會計為已提交頁面。
整個 VMO 應一次解鎖，因此 offset 應為 0，而 size 應為 VMO 的目前大小 (與頁面對齊的大小，如 zx_vmo_get_size() 傳回)。需要 ZX_RIGHT_READ 或 ZX_RIGHT_WRITE 權限。
ZX_VMO_OP_CACHE_SYNC - 將指令快取與資料快取同步處理，讓指令擷取作業可看到先前的寫入作業。需要 ZX_RIGHT_READ 權限。
ZX_VMO_OP_CACHE_INVALIDATE - 執行快取失效作業，以便日後的讀取作業查看主記憶體的外部變更。請注意，只有在 kernel.enable-debugging-syscalls 為 true 時，才能執行這項操作。如果未啟用系統呼叫偵錯功能，這項作業會失敗，並顯示「Requires the ZX_RIGHT_WRITE right」ZX_ERR_NOT_SUPPORTED。
ZX_VMO_OP_CACHE_CLEAN - Clean (write back) data caches, so previous writes are visible in main
memory.
需要 ZX_RIGHT_READ 權限。
ZX_VMO_OP_CACHE_CLEAN_INVALIDATE - Performs cache clean and invalidate operations together.
需要 ZX_RIGHT_READ 權限。
ZX_VMO_OP_DONT_NEED - Hints that pages in the specified range are not needed anymore and should
be considered for memory reclamation. 適用於以 zx_pager_create_vmo() 建立的 VMO；其他 VMO 則會直接成功。
這項作業只會套用至指定範圍內已提交的頁面，也就是說，不會因此提交任何新頁面。如有需要，offset 會向下捨入至前一個頁面邊界，而 offset+size 則會向上捨入至下一個頁面邊界。
ZX_VMO_OP_ALWAYS_NEED - Hints that pages in the specified range are important and should be
protected from memory reclamation. 當系統面臨極端的記憶體壓力時，核心可能會決定覆寫這項提示。此外，這個提示也不會防止系統透過記憶體回收以外的方式釋出網頁 (例如取消認可、VMO 大小調整或 VMO 毀損)。適用於以 zx_pager_create_vmo() 建立的 VMO；其他 VMO 則會直接成功。
這可能會在適用時提交指定範圍內的頁面，例如，如果 VMO 直接由分頁支援，系統會提交其頁面；如果是複製，則會提交父項中對複製可見的頁面。如有需要，offset 會向下捨入至前一頁的邊界，而 offset+size 則會向上捨入至下一頁的邊界。
請注意，ZX_VMO_OP_DONT_NEED 不會復原先前的 ZX_VMO_OP_ALWAYS_NEED，ZX_VMO_OP_ALWAYS_NEED 提示具有黏性，直到核心因記憶體壓力而決定覆寫提示為止。
權限
如果 op 為 ZX_VMO_OP_COMMIT，則 handle 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_WRITE。
如果 op 為 ZX_VMO_OP_DECOMMIT，則 handle 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_WRITE。
如果 op 為 ZX_VMO_OP_PREFETCH，則 handle 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_READ。
如果 op 為 ZX_VMO_OP_CACHE_SYNC，則 handle 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_READ。
如果 op 為 ZX_VMO_OP_CACHE_INVALIDATE，則 handle 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_WRITE。
如果 op 為 ZX_VMO_OP_CACHE_CLEAN，則 handle 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_READ。
如果 op 為 ZX_VMO_OP_CACHE_CLEAN_INVALIDATE，則 handle 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_READ。
傳回值
zx_vmo_op_range() 會在成功時傳回 ZX_OK。如果失敗，系統會傳回負數錯誤值。
錯誤
ZX_ERR_BAD_HANDLE handle 不是有效的控制代碼。
ZX_ERR_OUT_OF_RANGE 偏移和大小指定的記憶體範圍無效。
ZX_ERR_NO_MEMORY 為 ZX_VMO_OP_COMMIT、ZX_VMO_OP_PREFETCH 或 ZX_VMO_OP_ZERO 分配要提交的頁面時發生錯誤。
ZX_ERR_WRONG_TYPE handle 不是 VMO 控制代碼。
ZX_ERR_ACCESS_DENIED handle 的權限不足，無法執行這項作業。
ZX_ERR_INVALID_ARGS buffer 是無效指標 (如果作業需要)，op 不是有效作業，size 為零且 op 是快取作業，或 op 為 ZX_VMO_OP_DECOMMIT 且範圍未與頁面對齊。
ZX_ERR_NOT_SUPPORTED 符合下列任一條件：
- op 為
ZX_VMO_OP_LOCK、ZX_VMO_OP_TRY_LOCK或ZX_VMO_OP_UNLOCK，且 VMO 並非以ZX_VMO_DISCARDABLE建立。 - op 為
ZX_VMO_OP_DECOMMIT，且基礎 VMO 不允許取消提交。 - op 為
ZX_VMO_OP_CACHE_INVALIDATE，且kernel.enable-debugging-syscalls為 false。 - op 為
ZX_VMO_OP_CACHE_SYNC、ZX_VMO_OP_CACHE_INVALIDATE、ZX_VMO_OP_CACHE_CLEAN或ZX_VMO_OP_CACHE_CLEAN_INVALIDATE，且 VMO 是以zx_vmo_create_physical()建立或衍生而來
ZX_ERR_UNAVAILABLE op 為 ZX_VMO_OP_TRY_LOCK，VMO 可捨棄，且核心已捨棄 VMO。
ZX_ERR_BAD_STATE op 為 ZX_VMO_OP_COMMIT 或 ZX_VMO_OP_PREFETCH，VMO 由呼叫器支援，且呼叫器或 VMO 處於不良狀態，導致無法填入要求的頁面。op 為 ZX_VMO_OP_UNLOCK，VMO 可捨棄，且 VMO 先前未鎖定。
ZX_ERR_IO op 為 ZX_VMO_OP_COMMIT 或 ZX_VMO_OP_PREFETCH，VMO 由分頁器支援，且分頁器在提交要求的頁面時發生 I/O 錯誤。
ZX_ERR_IO_DATA_INTEGRITY op 為 ZX_VMO_OP_COMMIT 或 ZX_VMO_OP_PREFETCH 時，VMO 會由呼叫器備份，且呼叫器讀取的待提交頁面內容已損毀。