zx_vmar_map_clock

摘要

對應核心時鐘物件的狀態。

宣告

zx_status_t zx_vmar_map_clock(zx_handle_t handle,
                              zx_vm_option_t options,
                              uint64_t vmar_offset,
                              zx_handle_t clock_handle,
                              uint64_t len,
                              user_out_ptr<zx_vaddr_t> mapped_addr);

說明

將指定時脈的狀態對應至指定虛擬記憶體位址區域。對應會保留對基礎虛擬記憶體物件的參照，因此關閉時鐘控制代碼不會移除這個函式新增的對應。指定的 options 與呼叫 zx_vmar_map() 時使用的相同，但下列選項明確遭到禁止，一律會導致錯誤：

  • ZX_VM_PERM_WRITE
  • ZX_VM_PERM_EXECUTE
  • ZX_VM_PERM_READ_IF_XOM_UNSUPPORTED

此外，系統不會提供任何 vmo_offet，且傳遞的長度必須是使用針對時鐘物件執行的 zx_object_get_info() 呼叫回報的長度，且該時鐘物件具有 ZX_INFO_CLOCK_MAPPED_SIZE 主題。請勿部分對應時鐘狀態。

無論使用者傳遞的選項為何，使用這個系統呼叫建立的對應項一律無法調整大小。

除了具備足夠的 VMAR 權限來建立對應之外，clock_handle 也必須具備 ZX_RIGHT_READ 和 ZX_RIGHT_MAP 權限。

解除對應時鐘的方式與 VMO 相同，只要將原始對應的位址和長度傳遞至 zx_vmar_unmap() 的呼叫即可。

使用者對應時鐘的控制代碼後，可以關閉控制代碼，但仍可讀取時鐘的狀態。 關閉時鐘控制代碼不會毀損對應，只有正確建構的 zx_vmar_unmap() 呼叫才能執行這項操作。

權限

handle 必須為 ZX_OBJ_TYPE_VMAR 類型。

clock_handle 必須為 ZX_OBJ_TYPE_CLOCK 類型。

傳回值

成功時，zx_vmar_map_clock() 會傳回 ZX_OK 和對應的絕對基底位址 (透過 mapped_addr)。基底位址會與頁面對齊，且不為零。如果失敗，系統會傳回負數錯誤值。

錯誤

ZX_ERR_BAD_HANDLE handle 或 clock_handle 不是有效的控制代碼。

ZX_ERR_WRONG_TYPE handle 或 clock_handle 分別不是 VMAR 或 Clock 控制代碼。

ZX_ERR_BAD_STATE handle 是指已毀損的 VMAR。

ZX_ERR_INVALID_ARGS，適用於下列任一情況：

  • len 與 ZX_INFO_CLOCK_MAPPED_SIZE 回報的對應大小不符。
  • options 包含上述明確禁止的其中一個標記。

請參閱 zx_vmar_map() 可能傳回的錯誤，瞭解這兩個系統呼叫可能出現的其他常見錯誤。

附註

使用 ZX_INFO_VMAR_MAPS 或 ZX_INFO_PROCESS_MAPS 主題列舉的對應項目 (搭配 zx_object_get_info() 系統呼叫) 會包含與對應 VMO 相同的資訊，但有下列例外狀況：

  • 字串「kernel-clock」會以對應名稱的形式傳回
  • 對應項目的 KOID，回報為時鐘物件的 KOID。

另請參閱