ZX_vmo_op_range

摘要

在 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 的長度，以位元組為單位，用於執行運算。

運算 要執行的作業：

buffer 和 buffer_size 為必要或未使用，視下方所述的運算而定。

ZX_VMO_OP_COMMIT - 自 VMO 的位元組偏移起提交相當於網頁大小的 size 個位元組。 詳情請參閱 vm 物件說明文件。 必須有 ZX_RIGHT_WRITE 右側的值。

ZX_VMO_OP_DECOMMIT：發布先前承諾為 VMO 的一系列頁面 設為 offset+size，如此即可將範圍的位元組重設為 0。必須有 ZX_RIGHT_WRITE 右側的值。 這個選項僅適用於透過 zx_vmo_create() 建立的 VM，而沒有配量 以及這類 VM 的切片子項您提供的範圍必須對齊頁面。

ZX_VMO_OP_PREFETCH - 從為 VMO。實際網頁不一定要經過測試，但日後讀取範圍時應有類似 效能特性，就好像把範圍替換為讀取範圍一樣。 必須有 ZX_RIGHT_READ 右側的值。

ZX_VMO_OP_ZERO：將 VMO 中的位元組範圍從 offset 重設為 offset+size 0.這在語意上等同於使用 zx_vmo_write()，但可執行更多工作 去除多餘的共用頁面來節省記憶體必須有 ZX_RIGHT_WRITE 右側的值。

ZX_VMO_OP_LOCK - 鎖定使用 ZX_VMO_DISCARDABLE 建立的 VMO 中的多個頁面，防止 這些物件就會被核心捨棄能夠保證成功鎖定 VMO 並歸還 如果引數有效，則為 ZX_OK。buffer 應指向 zx_vmo_lock_state_t 結構，而 buffer_size 應配合結構體。傳回已鎖定和先前鎖定的資訊 捨棄的範圍，讓用戶端可以視需要重新初始化已捨棄的內容。

整個 VMO 應同時鎖定，因此 offset 應為 0，且 size 應為目前的 VMO 的大小 (zx_vmo_get_size() 傳回的頁面對齊大小)。需要 ZX_RIGHT_READ或ZX_RIGHT_WRITE右側。請注意，鎖定本身不會提交 VMO；只會將 VMO 的狀態標示為「undiscardable」。

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 - 在 VMO 中使用 ZX_VMO_DISCARDABLE 建立多個頁面， 以防止核心捨棄這些物件只有在範圍尚未設定的情況下才會成功 就會遭到核心捨棄，否則將會失敗並顯示 ZX_ERR_UNAVAILABLE。這項作業 可做為 ZX_VMO_OP_LOCK 的輕量替代方案，用途在不鎖定 VMO 的情況下嘗試鎖定 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 的狀態標示為「undiscardable」。

ZX_VMO_OP_UNLOCK：解鎖 VMO 中使用 ZX_VMO_DISCARDABLE 建立的多個頁面， 表示核心可以在記憶體壓力下自行捨棄。已解鎖的網頁，並顯示 未捨棄的仍將視為已修訂網頁。

整個 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。如未啟用 syscall 偵錯，此作業 將於 ZX_ERR_NOT_SUPPORTED後失敗 必須有 ZX_RIGHT_WRITE 右側的值。

ZX_VMO_OP_CACHE_CLEAN：清除 (寫入) 資料快取，因此之前寫入的資料會顯示在主要資源中 記憶體用量 必須有 ZX_RIGHT_READ 右側的值。

ZX_VMO_OP_CACHE_CLEAN_INVALIDATE - 同時執行快取清理和撤銷作業。 必須有 ZX_RIGHT_READ 右側的值。

ZX_VMO_OP_DONT_NEED：提示指定範圍內的網頁不再需要， 才會視為記憶體回收。適合與以下列通訊協定建立的 VMO 搭配使用 zx_pager_create_vmo()；生成式 AI 的 和其他 VMO 一樣

這只適用於指定範圍內已修訂的網頁，也就是說，不會有新網頁 。如有需要，偏移值會無條件捨去至上一頁 界線和 offset + size 的值會四捨五入至下一個頁面邊界。

ZX_VMO_OP_ALWAYS_NEED：提示指定範圍內的網頁有重要性， 進而避免記憶體回收系統執行以下作業時，核心可能會決定覆寫這項提示： 暴露在極端記憶體壓力之中此外，這項提示也不會導致其他頁面無法以其他方式釋放網頁 而非記憶體重組 (例如解構作業、VMO 大小調整或 VMO 刪除)。適合搭配 使用 zx_pager_create_vmo() 建立的 VMO；經常 就必須為其他 VMO 輸入成功

在適用情況下，可能會修訂指定範圍內的網頁，例如如果 VMO 直接支援 系統將提交其頁面；如果是本機副本，則會提交父項中可見的頁面 並維護本機副本的採用來源如有需要，偏移值會無條件捨去至上一頁 界線和 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 帳號代碼不是有效的帳號代碼。

ZX_ERR_OUT_OF_RANGE 由 offset 和 size 指定的無效記憶體範圍。

ZX_ERR_NO_MEMORY 將配置用於 ZX_VMO_OP_COMMIT、ZX_VMO_OP_PREFETCH 或 ZX_VMO_OP_ZERO失敗。

ZX_ERR_WRONG_TYPE 帳號代碼不是 VMO 控制代碼。

ZX_ERR_ACCESS_DENIED 帳號代碼沒有足夠的權限可執行該作業。

ZX_ERR_INVALID_ARGS buffer 為無效指標 (如果作業需要)，op 不是 有效作業，size 為零且 op 為快取作業，或 op 為 ZX_VMO_OP_DECOMMIT 且範圍沒有對齊頁面。

ZX_ERR_NOT_SUPPORTED： - 運算為 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 運算為 ZX_VMO_OP_TRY_LOCK，VMO 可以捨棄，VMO 也 就會遭到核心捨棄

ZX_ERR_BAD_STATE 運算為 ZX_VMO_OP_COMMIT 或 ZX_VMO_OP_PREFETCH，VMO 是由 Pager 和 Pager 或 VMO 的狀態錯誤，因此無法填入要求的網頁。 op 是 ZX_VMO_OP_UNLOCK，VMO 可以捨棄，VMO 先前並未鎖定。

ZX_ERR_IO 運算為 ZX_VMO_OP_COMMIT 或 ZX_VMO_OP_PREFETCH，VMO 是由呼叫器提供支援， 網頁伺服器提交要求的網頁時發生 I/O 錯誤。

ZX_ERR_IO_DATA_INTEGRITY 運算為 ZX_VMO_OP_COMMIT 或 ZX_VMO_OP_PREFETCH，VMO 會 由網頁工具提供支援，以及針對所提交網頁的呼叫器所讀取的內容 毀損。

另請參閱

• zx_vmo_create()
• zx_vmo_create_child()
• zx_vmo_get_size()
• zx_vmo_read()
• zx_vmo_set_size()
• zx_vmo_write()