摘要
固定頁面並授予裝置存取權。
宣告
#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 所代表的硬體交易 ID 存取這些頁面的權限，且這些權限會在 options 中指定。
偏移值必須對齊頁面邊界。
options 是位元欄位，可能包含 ZX_BTI_PERM_READ、ZX_BTI_PERM_WRITE、ZX_BTI_PERM_EXECUTE、ZX_BTI_COMPRESS 和 ZX_BTI_CONTIGUOUS 中的一或多個值。為了讓呼叫成功，vmo 必須具備「options」中設定的權限旗標對應的「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會向上捨入 (每個位址代表一連串的 最小連續性位元組，如果大小不是 最小連續性的倍數，最後一個位元組可能會較短)。系統會保證所有傳回的地址都會以最小連續性對齊。請注意，minimum-contiguity 可透過zx_object_get_info()進行探索。 - 如果已設定
ZX_BTI_CONTIGUOUS，則為記憶體開頭的單一位址。
num_addrs 是 addrs 陣列中的項目數量。如果 num_addrs 與上述計算的值不符，則表示發生錯誤。
PMT 會保留關聯 VMO 的參照，因此在解除 PMT 固定之前，基礎 VMO 不會遭到銷毀。
可調整大小的 VMOs 可釘選。如果呼叫 zx_vmo_set_size() 會捨棄已固定的頁面，該呼叫就會失敗。
選項
ZX_BTI_PERM_READ、ZX_BTI_PERM_WRITE和ZX_BTI_PERM_EXECUTE會定義硬體匯流排交易啟動程序可使用的存取類型。ZX_BTI_COMPRESS會讓傳回的地址清單每個 minimum-contiguity 位元組區塊包含一個項目，而非每個 PAGE_SIZE 一個項目。
權限
handle 必須是 ZX_OBJ_TYPE_BTI 類型，且具有 ZX_RIGHT_MAP。
vmo 必須是 ZX_OBJ_TYPE_VMO 類型，且包含 ZX_RIGHT_MAP。
如果是選項和 ZX_BTI_PERM_READ，vmo 必須是 ZX_OBJ_TYPE_VMO 類型，並具有 ZX_RIGHT_READ。
如果是選項和 ZX_BTI_PERM_WRITE，vmo 必須是 ZX_OBJ_TYPE_VMO 類型，並具有 ZX_RIGHT_WRITE。
如果是選項和 ZX_BTI_PERM_EXECUTE，vmo 必須是 ZX_OBJ_TYPE_VMO 類型，並具有 ZX_RIGHT_READ。
傳回值
如果成功，zx_bti_pin() 會傳回 ZX_OK。系統會在 addrs 中寫入要求的 VMO 頁面裝置實體位址。系統會透過 pmt 傳回已建立的固定記憶體權杖的句柄。當不再需要 PMT 時，應叫用 zx_pmt_unpin()。
如果失敗，系統會傳回負值錯誤。
錯誤
ZX_ERR_BAD_HANDLE handle 或 vmo 不是有效的 handle。
ZX_ERR_WRONG_TYPE handle 不是 BTI handle，或是 vmo 不是 VMO handle。
ZX_ERR_ACCESS_DENIED handle 或 vmo 沒有 ZX_RIGHT_MAP，或是 options 包含權限標記，對應至 vmo 沒有的權利。
ZX_ERR_INVALID_ARGS options 為 0 或包含未定義的標記、addrs 或 pmt 不是有效的指標、num_addrs 與傳回的項目數量不符、num_addrs 過大或offset 或size 未對齊頁面。
ZX_ERR_OUT_OF_RANGE offset + size 超出 vmo 的範圍。
ZX_ERR_UNAVAILABLE (暫時) 目前無法固定要求範圍內的至少一個網頁。
ZX_ERR_NO_MEMORY 記憶體不足導致失敗。使用者空間沒有適當的方式來處理這個 (不太可能發生的) 錯誤。日後的版本將不會再發生這個錯誤。