摘要
建立 VM 物件的子項。
宣告
#include <zircon/syscalls.h>
zx_status_t zx_vmo_create_child(zx_handle_t handle,
uint32_t options,
uint64_t offset,
uint64_t size,
zx_handle_t* out);
說明
zx_vmo_create_child() 會建立新的虛擬記憶體物件 (VMO)，做為現有 VMO 的子項。語意行為取決於子項目的類型。
如果成功，系統會傳回一個控制代碼，代表具有要求大小的物件。
options 必須包含下列其中一個旗標，才能指定子項類型：
ZX_VMO_CHILD_SNAPSHOT- 建立子項，其行為如同執行急切複製作業。發生寫入作業時，父項和子項都會執行延遲複製作業。延遲複製可讓子項和父項彼此分歧。從父項 VMO 大小以外的範圍讀取任何內容時，會包含零，而寫入作業則會配置新的零填滿頁面。使用ZX_VMO_CHILD_NO_WRITE(而非ZX_VMO_CHILD_RESIZABLE) 建立 VMO 時，系統會建立不可變動的 VMO。
下列項目不支援這個標記：
- 具有釘選區域的 VMO。
- 以 zx_vmo_create_physical() 或 zx_vmo_create_contiguous() 建立或衍生而來的 VMO。
- 由使用者呼叫器支援的 VMO。
如要瞭解 VMO 系統呼叫與子項的互動，請參閱附註。
ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE- 建立子項，其行為至少要符合寫入時複製語意。對子項執行的任何寫入作業都會從父項帶入頁面副本，之後其內容可能會與父項不同。在寫入及複製網頁之前，系統允許讀取作業，但如果父項執行寫入作業，則不保證讀取作業會傳回變更的值。這個旗標可能無法用於以zx_vmo_create_physical()、zx_vmo_create_contiguous()或這類 VMO 的子項建立的 VMO。如要瞭解 VMO 系統呼叫與子項的互動，請參閱附註。ZX_VMO_CHILD_SNAPSHOT_MODIFIED- 建立子項，其行為就像是在父項中任何未由分頁支援的頁面上執行急切複製作業一樣，也就是由分頁支援的 VMO 子項修改的頁面。以分頁支援的頁面至少會有寫入時複製語意。這個標記可能無法用於以zx_vmo_create_physical()、zx_vmo_create_contiguous()建立的 VMO，或包含已釘選頁面的 VMO，以及這類 VMO 的子項。如果使用SNAPSHOT_AT_LEAST_ON_WRITE建立的 VMO 具有非切片的子項，或不是分頁支援 VMO 的子項，也不支援這個標記。如要瞭解 VMO 系統呼叫與子項的互動，請參閱附註。ZX_VMO_CHILD_REFERENCE- 建立 VMO 的參照。對參照 VMO 執行的所有作業，行為都與對父項執行的作業相同。參照一律會跨越整個父項，且 offset 和 size 必須為 0。如果使用者想使用ZX_VMO_ZERO_CHILDREN信號追蹤 VMO 的待處理參照，這項功能就非常實用。如要進一步瞭解這項信號，請參閱「附註」。這個標記「不得」用於以zx_vmo_create_physical()、zx_vmo_create_contiguous()或這類 VMO 的子項建立的 VMO。ZX_VMO_CHILD_SLICE- 建立可直接讀取/寫入父項部分內容的切片。切片與參照的不同之處在於，切片只允許存取父項 VMO 的子範圍，且支援不同的父項 VMO 類型：ZX_VMO_CHILD_SLICE可與使用zx_vmo_create_physical()或zx_vmo_create_contiguous()建立的 VMO 及其後代搭配使用。這個標記「不得」與使用ZX_VMO_RESIZABLE選項建立的 VMO 搭配使用。
此外，options 可以包含零或多個下列標記，進一步指定子項的行為：
ZX_VMO_CHILD_RESIZABLE- 建立可調整大小的子項 VMO。這與ZX_VMO_CHILD_SLICE不相容。ZX_VMO_CHILD_NO_WRITE- 建立無法寫入的子項。這與ZX_VMO_CHILD_RESIZABLE不相容。
偏移必須與頁面對齊。
offset + size 不得超過 64 位元無正負號值的範圍。
偏移和大小都可能超出原始 VMO 的大小。
VMO 大小會向上取整至下一個頁面大小邊界。
VMO 的內容大小會初始化為指定 (未四捨五入) 的大小。
搭配 ZX_PROP_VMO_CONTENT_SIZE 使用 zx_object_get_property()，即可讀取 VMO 的內容大小。搭配 ZX_PROP_VMO_CONTENT_SIZE 使用 zx_object_set_property()，即可設定 VMO 的內容大小，而不實際調整 VMO 大小。
根據預設，子帳號的權利與原始帳號相同，但有幾項例外情況。如要瞭解各項權利的詳細資訊，請參閱 zx_vmo_create()。
如果 options 包含 ZX_VMO_CHILD_RESIZABLE，系統會新增 ZX_RIGHT_RESIZE。
如果是 ZX_VMO_CHILD_REFERENCE，ZX_VMO_CHILD_RESIZABLE 選項會控制是否可使用 out 中傳回的參照控點，調整父項 VMO 的大小。如果父項 VMO 可調整大小，則無論是否存在 ZX_VMO_CHILD_RESIZABLE，參考項目都會在父項 VMO 上看到大小調整。不過，只有在父項 VMO 可調整大小時，才支援 ZX_VMO_CHILD_RESIZABLE，也就是說，您無法建立不可調整大小的 VMO 可調整大小參照。
在所有情況下，如果設定 ZX_VMO_NO_WRITE，系統就會移除 ZX_RIGHT_WRITE。
如果 options 為 ZX_VMO_CHILD_SNAPSHOT、ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE 或 ZX_VMO_CHILD_SNAPSHOT_MODIFIED，且未設定 ZX_VMO_CHILD_NO_WRITE，系統會新增 ZX_RIGHT_WRITE 並移除 ZX_RIGHT_EXECUTE。
附註
建立子項 VMO 會導致現有 (來源) VMO ZX_VMO_ZERO_CHILDREN 信號失效。只有在最後一個子項遭到毀損，且這些子項沒有對應到位址空間時，ZX_VMO_ZERO_CHILDREN 才會再次啟動。
非切片子項 VMO 會透過下列方式與 VMO 系統呼叫互動：
- 子項的
zx_vmo_op_range()COMMIT 模式會將頁面提交至子項，這些頁面與父項的對應頁面具有相同內容。如果這些頁面是由分頁器提供，這項作業也會在父項中提交這些頁面。否則，如果這些頁面未在上層中提交，系統會直接將填滿零的頁面提交至子項，不會影響上層。 - 不支援
zx_vmo_op_range()的 DECOMMIT 模式。
權限
handle 必須是 ZX_OBJ_TYPE_VMO 型別，且具有 ZX_RIGHT_DUPLICATE 和 ZX_RIGHT_READ。
傳回值
zx_vmo_create_child() 會在成功時傳回 ZX_OK。如果失敗，系統會傳回負數錯誤值。
錯誤
ZX_ERR_BAD_TYPE 輸入控制代碼不是 VMO。
ZX_ERR_ACCESS_DENIED 輸入控制代碼的權限不足。
ZX_ERR_INVALID_ARGS out 是無效的指標或 NULL
或位移並未與頁面對齊，或提供的 options 組合不相容。
ZX_ERR_OUT_OF_RANGE offset + size 過大。
ZX_ERR_NO_MEMORY 記憶體不足，導致失敗。
使用者空間無法妥善處理這個 (不太可能發生的) 錯誤。
日後建構版本將不會再發生這個錯誤。
ZX_ERR_BAD_STATE 由於 VMO 有一些已釘選的頁面，因此無法建立 COW 子項。
ZX_ERR_NOT_SUPPORTED 輸入控制代碼是可捨棄的 VMO，或是輸入控制代碼是可調整大小的 VMO，且選項包含 ZX_VMO_CHILD_SLICE。