摘要
固定頁面並授權裝置存取。
宣告
#include <zircon/syscalls.h>
zx_status_t zx_bti_pin(zx_handle_t handle,
uint32_t options,
zx_handle_t vmo,
uint64_t offset,
uint64_t size,
zx_paddr_t* addrs,
size_t num_addrs,
zx_handle_t* pmt);
說明
zx_bti_pin() 會固定 VMO 的頁面 (例如防止使用 zx_vmo_op_range() 停用這些頁面)，並授予 BTI 代表能存取這些網頁的權限，並提供選項中指定的權限。
offset 必須與頁面邊界對齊。
options 是位元欄位，可包含一或多個 ZX_BTI_PERM_READ、ZX_BTI_PERM_WRITE、ZX_BTI_PERM_EXECUTE、ZX_BTI_COMPRESS 和 ZX_BTI_CONTIGUOUS。為了讓呼叫成功，vmo 必須具備與「選項」中設定的權限標記相對應的 READ/WRITE 權限。(注意：ZX_BTI_PERM_EXECUTE 需要 ZX_RIGHT_READ，而非 ZX_RIGHT_EXECUTE)。只有在透過 zx_vmo_create_contiguous() 或 zx_vmo_create_physical() 分配 vmo 時，才能使用 ZX_BTI_CONTIGUOUS。ZX_BTI_COMPRESS 和 ZX_BTI_CONTIGUOUS 互斥，無法共同存在。
如果 vmo 中指定的範圍由 offset 和 size 含有未修訂的頁面，則如果叫用這個函式，將會導致這些網頁修訂完成。失敗時，無法定義其是否已修訂。
addrs 會填入所要求 VMO 頁面的裝置實體位址。這些位址可能會提供給裝置，且裝置必須透過與 BTI 相關聯的硬體交易 ID 核發記憶體交易。傳回的地址數量取決於是否有提供 ZX_BTI_COMPRESS 或 ZX_BTI_CONTIGUOUS 選項。位址數量有以下三種可能性：
- 如果兩者皆未設定，則每個網頁 (
size / PAGE_SIZE) 各一個。 - 如果已設定
ZX_BTI_COMPRESS，則系統會將size / minimum-contiguity四捨五入 (每個位址代表執行的「最小連續性」執行次數，如果 size 並非最小連續性的倍數，最後一個位址則可能較短)。我們保證所有傳回的位址都會以最小連續性對齊。請注意，您可以透過zx_object_get_info()找到最小連續性。 - 如果已設定
ZX_BTI_CONTIGUOUS，則記憶體開頭的單一位址。
num_addrs 是 addrs 陣列中的項目數量，這是 num_addrs 的錯誤，與上述計算的值不符。
PMT 會保留關聯 VMO 的參照，因此在取消固定 PMT 之前，基礎 VMO 不會遭到刪除。
如有需要，您可以固定可調整大小的 VMO。如果呼叫 zx_vmo_set_size() 會捨棄固定的頁面，該呼叫就會失敗。
選項
ZX_BTI_PERM_READ、ZX_BTI_PERM_WRITE和ZX_BTI_PERM_EXECUTE定義了硬體匯流排交易發起器有權使用的存取權類型。ZX_BTI_COMPRESS會使傳回的地址清單在每個「最少連續」位元組區塊中包含一個項目，而非每個 PAGE_SIZE 一個。
權限
handle 必須是 ZX_OBJ_TYPE_BTI 類型，且具有 ZX_RIGHT_MAP。
vmo 必須是 ZX_OBJ_TYPE_VMO 類型且具有 ZX_RIGHT_MAP。
如果 options 和 ZX_BTI_PERM_READ，vmo 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_READ。
如果 options 和 ZX_BTI_PERM_WRITE，vmo 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_WRITE。
如果 options 和 ZX_BTI_PERM_EXECUTE，vmo 必須為 ZX_OBJ_TYPE_VMO 類型，且具有 ZX_RIGHT_READ。
傳回值
成功時，zx_bti_pin() 會傳回 ZX_OK。所要求 VMO 頁面的裝置實際位址是以「addrs」編寫。系統會透過 pmt 傳回已建立的固定記憶體權杖的控制代碼。當您不再需要 PMT 時，應叫用 zx_pmt_unpin()。
如果失敗，系統會傳回負值錯誤值。
錯誤
ZX_ERR_BAD_HANDLE 控制代碼或 vmo 不是有效的帳號代碼。
ZX_ERR_WRONG_TYPE 帳號代碼不是 BTI 控點，或 vmo 不是 VMO 帳號代碼。
ZX_ERR_ACCESS_DENIED 處理常式或 vmo 沒有 ZX_RIGHT_MAP，或者 options 包含與 vmo 沒有權限對應的權限旗標。
ZX_ERR_INVALID_ARGS options 為 0 或包含未定義的標記，addrs 或 pmt 是無效指標；num_addrs 與要傳回的項目數量不同，或者 offset 或 size 則並非頁面對齊。
ZX_ERR_OUT_OF_RANGE offset + size 超過 vmo 的邊界。
ZX_ERR_UNAVAILABLE (臨時) 在要求範圍內，目前至少有一個頁面無法固定。
ZX_ERR_NO_MEMORY 因記憶體不足而失敗。使用者空間不可能處理這個錯誤 (機率也不高)。日後的建構作業不會再發生這個錯誤。