fuchsia.sysmem2

分配系統記憶體緩衝區。

這個通訊協定未使用 Epitaph，

新增時間：19 歲

AllocateNonSharedCollection

代表單一用戶端 (也就是啟動者) 分配一個緩衝區集合，該用戶端同時也是唯一參與者 (從 sysmem 的觀點開始)。

此呼叫主要用於暫時/測試目的。這項呼叫會略過 fuchsia.sysmem2/BufferCollectionToken 階段，因此無法允許其他參與者指定其限制。

我們建議實際的客戶使用 fuchsia.sysmem2/Allocator.AllocateSharedCollection，讓相關參與者將 BufferCollectionToken 傳送給這些參與者，直接傳達自己的限制至 sysmem。

要求 collection_request。 fuchsia.sysmem2/BufferCollection 的伺服器端。

要求

名稱	類型
`payload`	`AllocatorAllocateNonSharedCollectionRequest`

AllocateSharedCollection

建立根 fuchsia.sysmem2/BufferCollectionToken。

您可以使用 fuchsia.sysmem2/BufferCollectionToken.Duplicate 將 BufferCollectionToken「重複」提供給參與者。每個 BufferCollectionToken 都可以使用 fuchsia.sysmem2/Allocator.BindSharedCollection 轉換為 fuchsia.sysmem2.BufferCollection。

您可以透過 fuchsia.sysmem2/BufferCollection.SetConstraints 設定緩衝區限制。

可以透過 fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated 判斷成功/失敗在緩衝區集合中填入緩衝區。

若關閉 BufferCollectionToken 或 BufferCollection 的用戶端 (沒有 Release 先結束)，則所有用戶端都會導致同一個故障網域結尾失敗，根據預設，是緩衝區收集的所有用戶端結束。如要瞭解如何在緩衝區集合中建立個別故障網域，請參閱 fuchsia.sysmem2/BufferCollection.SetDispensable 和 fuchsia.sysmem2/BufferCollection.AttachToken。

要求

名稱	類型
`payload`	`AllocatorAllocateSharedCollectionRequest`

BindSharedCollection

將 fuchsia.sysmem2/BufferCollectionToken 轉換為 fuchsia.sysmem2/BufferCollection。

在傳送這則訊息時，緩衝區集合尚未填入緩衝區，參與者必須先透過 BufferCollection 用戶端端傳送 fuchsia.sysmem2/BufferCollection.SetConstraints。

所有從根 BufferCollectionToken 複製 (透過 AllocateSharedCollection 建立) 複製的 BufferCollectionToken 都必須透過 BindSharedCollection (或 Releaseed) 「轉入」，且所有現有的 BufferCollection 用戶端結尾都必須傳送 SetConstraints 之後，邏輯 BufferCollection 才會填入緩衝區 (若無法滿足整體限制集，則會失敗)。

要求 token。使用 fuchsia.sysmem2/Allocator.AllocateSharedCollection 將管道的用戶端端點傳送至 sysmem，或使用 fuchsia.sysmem2/BufferCollectionToken.Duplicate 將伺服器端傳送至 sysmem。該憑證會「轉入」以換取 fuchsia.sysmem2/BufferCollection。
要求 buffer_collection_request。 fuchsia.sysmem2/BufferCollection 管道結尾。傳送者會保留用戶端。BufferCollection 管道是單一參與者與邏輯緩衝區集合的連線。一般而言，會有其他參與者擁有自己的 BufferCollection 管道到邏輯緩衝區集合。

要求

名稱	類型
`payload`	`AllocatorBindSharedCollectionRequest`

GetVmoInfo

如果有 sysmem 提供的 VMO 控制代碼，這會傳回對應 sysmem 邏輯緩衝區的其他資訊。

大多數呼叫端會先複製 VMO 控制代碼，並將重複的副本傳送至這個呼叫。

如果用戶端為 sysmem 提供的 VMO 建立子項 VMO，則該子項 VMO 不會視為「sysmem VMO」來進行此呼叫。

要求 vmo A 處理常式提供給 sysmem 提供的 VMO (或查看錯誤)。

回應 buffer_collection_id 緩衝區集合 ID，每個開機時每個邏輯緩衝區集合的專屬 ID。
回應 buffer_index。緩衝區集合中的緩衝區索引。這與 fuchsia.sysmem2/BufferCollectionInfo.buffers 內緩衝區的索引相同。針對對應至相同邏輯緩衝區的所有 sysmem 提供 VMO，即使 VMO Kid 有所不同，buffer_index 仍會相同。buffer_index 僅在緩衝區集合的緩衝區間不重複。就特定緩衝區而言，每次開機的 buffer_collection_id 和 buffer_index 組合都不重複。
回應 close_weak_asap。如果 vmo 是回應速度緩慢 sysmem VMO 的控制代碼，則回應中會設定 close_weak_asap 欄位。當所有針對緩衝區的 VMO 控制代碼都應盡快關閉時，這個控制代碼將會發出 ZX_EVENTPAIR_PEER_CLOSED 信號。系統會在所有強力的 sysmem VMO 關閉至緩衝區後 (包括任何透過強式 BufferCollectionToken 或強 BufferCollection 間接保留) 後短暫發出信號，在 ZX_EVENTPAIR_PEER_CLOSED 時，即使用戶端仍保留微弱的 sysmem VMO 處理給緩衝區，因而導致 VMO 外洩 (因用戶端仍容納 sysmem 的 sysmem 記錄) 而引發大量 sysmem 的處理記錄而造成 VMO 流失。集合的緩衝區可以彼此獨立。ZX_EVENTPAIR_PEER_CLOSED 在回應送達用戶端前可能已發出信號。未準備好處理低強度 sysmem VMO 的用戶端，看到這個欄位組合時，可以關閉緩衝區的所有控制代碼，並導致任何相關要求失敗。

錯誤 [fuchsia.sysmem2/Error.NOT_FOUND]：vmo 並非 sysmem VMO。高強度和低強度的 sysmem VMO 都可傳遞至此呼叫，而傳入至此呼叫的 VMO 控制代碼本身會保留 VMO 的資訊，以便回應此呼叫。因此，ZX_ERR_NOT_FOUND 錯誤並不明確 (即使 VMO 在呼叫時沒有其他處理序；即使在 GetVmoInfo 回應送達用戶端前已關閉其他控制代碼也一樣)。
錯誤 [fuchsia.sysmem2/Error.HANDLE_ACCESS_DENIED] 由於權利/能力受到吸引，vmo 無法與 GetVmoInfo 搭配使用。VMO 必須可透過 ZX_INFO_HANDLE_BASIC 主題的 zx_vmo_get_info 使用。
錯誤 [fuchsia.sysmem2/Error.UNSPECIFIED] 要求因不明原因失敗。詳情請參閱記錄。
錯誤 [fuchsia.sysmem2/Error.PROTOCOL_DEVIATION] 未設定 vmo 欄位，或是要求欄位發生其他問題。

要求

名稱	類型
`payload`	`AllocatorGetVmoInfoRequest`

回應

名稱	類型
`payload`	`Allocator_GetVmoInfo_Result`

SetDebugClientInfo

設定 Smem 可使用的目前用戶端資訊，協助診斷記憶體流失和配置延遲，等候參與者傳送 fuchsia.sysmem2/BufferCollection.SetConstraints。

這會針對這個 fuchsia.sysmem2/Allocator 建立的所有 fuchsia.sysmem2/Node1{Node1} 子標籤 { 後續建立的偵錯用戶端資訊 (fuchsia.sysmem2 Allocator.BindSharedCollection fuchsia.sysmem2 Allocator.SetDebugClientInfoBufferCollectionBufferCollection

您之後可以傳送 fuchsia.sysmem2/Node.SetDebugClientInfo，以個別 Node 覆寫這項資訊。

每 Allocator Node.1.fuchsia.sysmem2 Allocator.SetDebugClientInfo fuchsia.sysmem2 fuchsia.sysmem2 Node.SetDebugClientInfo fuchsia.sysmem2

要求 name 可以是任意字串，但目前的程序名稱 (請參閱 fsl::GetCurrentProcessName) 是不錯的預設值。
要求 id 可以是任意 ID，但目前的程序 ID (請參閱 fsl::GetCurrentProcessKoid) 是不錯的預設值。

要求

名稱	類型
`payload`	`AllocatorSetDebugClientInfoRequest`

ValidateBufferCollectionToken

檢查 sysmem 伺服器是否已得知 fuchsia.sysmem2/BufferCollectionToken。

透過此呼叫，用戶端可判斷傳入的憑證是否為 sysmem 伺服器已知的真實 sysmem 憑證，而不會因等待潛在假權杖永遠停滯，無法完成 fuchsia.sysmem2/BufferCollectionToken.DuplicateSync 或 fuchsia.sysmem2/BufferCollectionToken.Sync (其他兩個訊息)。如果用戶端信任權杖來源來提供實際權杖，則除了偵錯之外，通常不需要這個呼叫。

如果驗證失敗但有時成功，則憑證來源本身可能不會呼叫 fuchsia.sysmem2/BufferCollectionToken.Sync 或 fuchsia.sysmem2/BufferCollection.Sync。來源可能會更輕易使用 fuchsia.sysmem2/BufferCollectionToken.DuplicateSync 來複製憑證，因為該呼叫內建同步步驟。或者，由於緩衝區收集失敗會清除 sysmem 對相關權杖的追蹤，因此在 sysmem 伺服器處理這項呼叫之前，緩衝區收集可能會失敗。

這項呼叫對任何權杖沒有影響。

要求 token_server_koid。該管道可能是 BufferCollectionToken 頻道。可以透過 zx_object_get_info ZX_INFO_HANDLE_BASIC related_koid 取得。

回應 is_known 為 true，表示 sysmem 在處理要求時知道該權杖，但不保證在用戶端收到回覆時權杖仍然有效。可確保該符記至少為真實符記，因此對該權杖的雙向呼叫不會永久停滯 (會快速失敗或成功，而非停滯)。如果權杖來源可信任以提供真實權杖，系統就能透過隱含方式得知這項資訊。值為「否」，表示 sysmem 處理此呼叫時， sysmem 不知道該憑證，但權杖先前可能曾有效，或可能尚未生效。或者，如果權杖傳送者不受信任的憑證提供實際權杖，則可能是假權杖。傳送者有責任與 sysmem 同步，確保 sysmem 可在將符記傳送給其他參與者之前，先得知先前建立/重複的權杖。

要求

名稱	類型
`payload`	`AllocatorValidateBufferCollectionTokenRequest`

回應

名稱	類型
`payload`	`Allocator_ValidateBufferCollectionToken_Result`

BufferCollection

一般而言，在匯總失敗時，sysmem 只會輸出一行申訴，且只會列出導致匯總失敗的具體原因，且幾乎不會出現任何背景資訊。雖然通常只要進行小規模的變更，且一切在微幅變更之前都能正常運作，通常就足以診斷問題，但這對首次使用新的緩衝區收集通常不太有幫助。特別是節點的子樹狀結構，例如 fuchsia.sysmem2/BufferCollection.AttachToken、fuchsia.sysmem2/BufferCollectionToken.SetDispensable、fuchsia.sysmem2/BufferCollectionTokenGroup

fuchsia.sysmem2/BufferCollection 是直接與 sysmem 之間的連線。緩衝區集合；緩衝區集合通常會與其他參與者分享，且其自身的 BufferCollection 用戶端與相同緩衝區集合相關聯。換句話說，BufferCollection 介面的執行個體是緩衝區集合的檢視畫面，而非緩衝區集合本身。

BufferCollection 連線可用於以非同步方式指示緩衝區集合已填入緩衝區的情況。

此外，sysmem 伺服器關閉了管道，表示用戶端應盡快關閉從 BufferCollection 取得的所有 VMO 控制代碼。

部分緩衝區集合可以使用足夠的記憶體，因此可利用 fuchsia.sysmem2/BufferCollection.AttachLifetimeTracking 進行即時配置重疊，這樣啟動器才能在啟動器分配新的緩衝區收集之前，判斷何時已完全解除緩衝區收集的緩衝區。

這個通訊協定未使用 Epitaph，

新增時間：19 歲

AttachLifetimeTracking

設定在已分配緩衝區時發出信號 (ZX_EVENTPAIR_PEER_CLOSED) 的事件組合，並且只在緩衝區收集作業中只保留指定數量的緩衝區。

fuchsia.sysmem2/BufferCollection.AttachLifetimeTracking 可讓用戶端等到舊的緩衝區收集完全或大部分取消分配後，再嘗試分配新的緩衝區收集。只有在其他緩衝區已完全取消配置時 (不只是用戶端未參照，這些緩衝區使用的所有記憶體都已完全收回/回收)，或是樹狀結構或子樹狀結構的配置或邏輯分配失敗時 (包括這個 fuchsia.sysmem2/BufferCollection)。

系統必須等到配置或邏輯配置完成，才會發出事件組合信號；在此之前，系統會忽略集合目前的緩衝區數量。

如果附加子樹狀結構的邏輯配置失敗 (使用 fuchsia.sysmem2/BufferCollection.AttachToken)，事件配對期間的伺服器端會在失敗期間關閉，無論在整體緩衝區集合中可能分配的緩衝區數量為何，都會關閉。這是為了讓邏輯分配與正常分配保持一致。

此事件發出的生命週期信號包括已配置緩衝區的非同步清除作業，且除非 VMO 處理緩衝區的所有容器都關閉這些 VMO 處理，否則無法進行非同步清除作業。因此，如果使用邏輯緩衝區集合的任何參與者不信任或較不可靠，用戶端應小心不要遭到封鎖，等待 ZX_EVENTPAIR_PEER_CLOSED 獲得訊號。無法分配新的/替換緩衝區集合會比一直處於停滯狀態好得多。

此機制旨在與 AttachLifetimeTracking 訊息類似的其他通訊協定相容；相同的 eventpair 控制代碼 (伺服器端) 可透過多項 AttachLifetimeTracking 訊息傳送到不同的通訊協定，而 ZX_EVENTPAIR_PEER_CLOSED 會在符合所有條件時向用戶端發出信號 (重複物件的所有容器所有容器都關閉了伺服器端控點)。此外，由於事件配對結束的運作方式，您可以在不阻止 ZX_EVENTPAIR_PEER_CLOSED 信號的情況下複製用戶端端。

伺服器刻意不會「信任」server_end 上的任何信號。此機制會刻意只使用 ZX_EVENTPAIR_PEER_CLOSED，後者無法設定「提前」，且只有在所有與伺服器端事件配對的控制代碼關閉時才會設定。其他信號沒有任何關聯，且用戶端應忽略 eventpair 兩端任何其他信號位元。

server_end 可能缺少 ZX_RIGHT_SIGNAL 或 ZX_RIGHT_SIGNAL_PEER，但必須具備 ZX_RIGHT_DUPLICATE (且轉移時必須具有 ZX_RIGHT_TRANSFER，且不會導致 BufferCollection 管道失敗)。

目前所有表格欄位均為必填。

要求 server_end。當緩衝區首次分配，且緩衝區數量小於或等於 buffers_remaining 時，Smem 伺服器將會關閉此事件配對控點。
要求 buffers_remaining 等待 buffers_remaining (或更少) 緩衝區以外的所有緩衝區。如果系統刻意關閉已知的緩衝區，導致資料仍可繼續使用 (例如，即使影片串流使用受保護的輸出緩衝區)，大於零的數值可能就很實用。緩衝區不在 BufferCollection 介面的範圍內 (至少目前) 會決定在不關閉的情況下可保留的緩衝區數量，但通常會落在 0 到 2 的範圍內。

要求

名稱	類型
`payload`	`BufferCollectionAttachLifetimeTrackingRequest`

AttachToken

如果現有集合的緩衝區數量、限制和參與者允許，請建立新的權杖，在現有的邏輯緩衝區集合中新增參與者。

這有助於替換失敗的參與者，和/或在已分配緩衝區後新增/重新加入參與者。

使用 fuchsia.sysmem2/BufferCollection.AttachToken 時，根層級為附加的 fuchsia.sysmem2/BufferCollectionToken 的子樹狀結構會經歷設定限製或關閉 fuchsia.sysmem2/Node 的正常程序。這項程序稱為「邏輯配置」。在文件中，大多數「分配」的執行個體也可以在保持有效狀態的情況下，將其解讀為「分配或邏輯分配」，但在大部分位置中直接說「分配」，為求簡潔說明，我們只對 AttachToken 中的文件提供「邏輯分配」詳細資料。

附加的 Node 失敗，不會套用至連接的 Node 父項。更廣泛來說，如果附加了子項，或者子項可分發，而且在邏輯分配之後發生失敗，子項 Node 失敗就無法與其父項 Node 聯繫 (請參閱 fuchsia.sysmem2/BufferCollectionToken.SetDispensable)。

在某些情況下，參與者可能會選擇一開始就特定委派參與者的指定例項使用可支付的權杖，之後如果委派參與者的第一個例項失敗，系統會把我用 AttachToken 建立的符記提供給委派參與者的新執行個體。

從 fuchsia.sysmem2/BufferCollectionToken 用戶端的角度來看，憑證的運作方式與其他符記相同。用戶端可以視需要fuchsia.sysmem2/BufferCollectionToken.Duplicate權杖，然後將權杖傳送給其他程序/參與者。應照常將 BufferCollectionToken Node 轉換為 BufferCollection Node，方法是傳送 fuchsia.sysmem2/Allocator.BindSharedCollection，或是傳送 fuchsia.sysmem2/BufferCollectionToken.Release，以關閉子樹狀結構。假設為前者，fuchsia.sysmem2/BufferCollection.SetConstraints 訊息或 fuchsia.sysmem2/BufferCollection.Release 訊息應傳送至 BufferCollection。

在子樹狀結構中，來自 fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated 的成功結果表示子樹參與者的限制可以使用現有的緩衝區集合、已經建立的fuchsia.sysmem2/BufferCollectionInfo ，以及這些現有的失敗結果表示無法使用現有的緩衝區集合以及已加入的參與者，滿足新參與者的限制。假設使用 SetDispensable 取代 AttachToken，或者使用的是一般符記，則建立新的集合可能會允許符合所有參與者的限制。

使用 AttachToken 建立的憑證會執行限制匯總，以及目前在緩衝區集合中生效的所有限制，加上要考量的附加權杖，以及附加權杖下的子權杖 (並非本身附加權杖本身或這類權杖下的子權杖)。這個子樹狀結構底下的其他子樹狀結構必須先完成邏輯分配，才能視為邏輯分配。

將現有緩衝區指派給參與者的 fuchsia.sysmem2/BufferCollectionConstraints.min_buffer_count_for_camping 等等，但子項無法在所有父項傳送 SetConstraints 之前按照邏輯進行分配。

另請參閱 fuchsia.sysmem2/BufferCollectionToken.SetDispensable，這是 AttachToken 建立的權杖 Node + 子項 Node (在已建立的子樹狀結構中，但不在子樹狀結構下方的任何子樹狀結構中) 在父項的分配或邏輯分配期間參與限制匯總及其父項。

與 fuchsia.sysmem2/BufferCollectionToken.Duplicate 類似，新建立的權杖需要先 fuchsia.sysmem2/Node.Sync 至 sysmem，才能將新的權杖傳遞至 BindSharedCollection。在將建立的 BufferCollectionToken 轉換為 BufferCollection 後，可透過 fuchsia.sysmem2/BufferCollection.Sync 完成新權杖的 Sync。或者，對新權杖的 fuchsia.sysmem2/BufferCollectionToken.Sync 也能正常運作。或使用 fuchsia.sysmem2/BufferCollectionToken.DuplicateSync 有效。一如往常，您可以在透過新建立的權杖傳送任何 BufferCollectionToken.Duplicate 訊息後啟動 BufferCollectionToken.Sync，以使用單次往返作業將這些額外的權杖同步處理至 sysmem。

目前所有表格欄位均為必填。

要求 rights_attentuation_mask，如此可載明子樹狀結構的 VMO 權利。這些 rights_attenuation_mask 的值不會造成任何解釋 (請注意，0 不在這份清單中)：
- ZX_RIGHT_SAME_RIGHTS (建議選項)
- 0xFFFFFFFF (在計算注意力面遮罩時相當合理)
要求 token_request。BufferCollectionToken 管道結尾的伺服器。用戶端會保留用戶端。

要求

名稱	類型
`payload`	`BufferCollectionAttachTokenRequest`

CheckAllBuffersAllocated

檢查輪詢時間是否已分配所有緩衝區。

如果已分配緩衝區收集，就會傳回成功。
如果緩衝區收集作業失敗，則會傳回與 fuchsia.sysmem2/BufferCollection/WaitForAllBuffersAllocated 相同的 fuchsia.sysmem2/Error。
錯誤 fuchsia.sysmem2/Error.PENDING 緩衝區收集尚未嘗試配置。這表示 WaitForAllBuffersAllocations 無法快速回應。

已新增：HEAD

要求

<EMPTY>

回應

名稱	類型
`payload`	`BufferCollection_CheckAllBuffersAllocated_Result`

GetBufferCollectionId

取得緩衝區集合 ID。fuchsia.sysmem2/Allocator.GetVmoInfo (以及集合內的 buffer_index) 也可取得此 ID。

這個呼叫主要在無法直接傳送 fuchsia.sysmem2/BufferCollectionToken 或 fuchsia.sysmem2/BufferCollection 的情況下，但只能傳輸 VMO 處理常式，而該處理常式可透過不同路徑建立的 BufferCollection 用戶端進行彙整。盡可能在可能的情況下直接傳遞 BufferCollectionToken 或 BufferCollection。

從 sysmem 以外的來源信任 buffer_collection_id 值類似信任 zircon 以外的來源 Koid 值。除非必要，否則兩者都應避免，而且這兩種方法都需要謹慎。在某些情況下，基於效率考量，透過通訊協定參照 buffer_collection_id 預先建立的 BufferCollection 可能是合理的做法，但聲稱為 buffer_collection_id 的傳入值並不足以合理化授予 buffer_collection_id 任何能力的傳送者。傳送者必須先傳送 Smem 確認為有效的 sysmem 控制代碼，以及哪個 sysmem 會對應至 buffer_collection_id 值，藉此向接收器證明傳送者是否已有 VMO，或已向該集合提交 BufferCollectionToken。如果傳送者僅證明傳送者僅具有 VMO，則接收方應謹慎避免假設傳送者擁有 BufferCollectionToken。

回應 buffer_collection_id 每次啟動的每個緩衝區集合都有這個 ID。每個緩衝區都由 buffer_collection_id 和 buffer_index 各自識別。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_GetBufferCollectionId_Result`

GetNodeRef

此取得一個控制代碼，可做為對任何 fuchsia.sysmem2/Node 呼叫 fuchsia.sysmem2/Node.IsAlternateFor 的參數。這個帳號代碼僅用於證明用戶端已從這個 Node 取得此控制代碼。

由於這是 get 並非集合，因此在 GetNodeRef 和 IsAlternateFor 呼叫之間不需要 fuchsia.sysmem2/Node.Sync，即使兩個呼叫通常位於不同的管道上。

另請參閱 fuchsia.sysmem2/Node.IsAlternateFor。

目前所有表格欄位均為必填。

回應 node_ref 這個帳號代碼可在其他 Node 管道中的 IsAlternateFor 傳送，證明用戶端已從這個 Node 取得控制代碼。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_GetNodeRef_Result`

IsAlternateFor

檢查呼叫 fuchsia.sysmem2/Node 是否位於子樹狀結構中，是否位於共同父項 fuchsia.sysmem2/BufferCollectionTokenGroup 的不同子項權杖 (與傳入的 node_ref 有關)。

此呼叫旨在協助清除重複許可控制項，以及進行偵錯。

您必須使用 fuchsia.sysmem2/Node.GetNodeRef 取得 node_ref。

node_ref 可以是重複的控制代碼；您不必在每次呼叫 fuchsia.sysmem2/Node.IsAlternateFor 時呼叫 GetNodeRef。

如果呼叫權杖因權杖可能有惡意/不受信任的提供者，而實際上並非有效憑證，請先呼叫 fuchsia.sysmem2/Allocator.ValidateBufferCollectionToken，而不要因 IsAlternateFor 因為呼叫權杖不是真實權杖而停滯 (並非真的跟 Smem 對話) 而無限制。另一個選項是先使用此憑證呼叫 fuchsia.sysmem2/Allocator.BindSharedCollection，進而驗證該權杖並將權杖轉換為 fuchsia.sysmem2/BufferCollection，然後呼叫 IsAlternateFor。

目前所有表格欄位均為必填。

回應 is_alternate
- true：呼叫節點與 node_ref Node 之間共同的第一個父項節點為 BufferCollectionTokenGroup。這表示呼叫 Node 和 node_ref Node 時，不會同時套用兩者的限制，而 sysmem 會選擇其中一個以上的限制條件，因為這兩者絕不會同時套用。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有一個子項子樹狀結構造成限制匯總。
- false：在呼叫 Node 與 node_ref Node 之間共用的第一個父項節點不是 BufferCollectionTokenGroup。目前同屬共用的第一個父項節點為 BufferCollectionToken 或 BufferCollection (無論 Release 為何)。這表示，如果涉及的任何父項 BufferCollectionTokenGroup 同時選取兩個 Node，呼叫 Node 和 node_ref Node 在邏輯分配的限制匯總期間，可能會同時套用這兩項限制。在此情況下，沒有任何 BufferCollectionTokenGroup 會直接禁止兩個 Node 和其限制都經過匯總，但即使為 false，如果一個或兩個 Node 具有直接或間接父項 BufferCollectionTokenGroup，而子樹狀結構與包含呼叫 Node 或 node_ref Node 的子樹狀結構不同，系統可能仍會將其中一個或兩個 Node 排除。

錯誤 [fuchsia.sysmem2/Error.NOT_FOUND] node_ref 與呼叫 Node 的緩衝區集合並未建立關聯。另一個此錯誤的原因是 node_ref 是具備足夠權限的 zx.Handle.EVENT 控制代碼，但實際上並非從 GetNodeRef 取得的實際 node_ref。
錯誤 [fuchsia.sysmem2/Error.PROTOCOL_DEVIATION] 呼叫端傳遞並非 zx.Handle:EVENT 控制代碼的 node_ref，或者在真實的 node_ref 上沒有所需權限。
這個呼叫不會傳回其他失敗的狀態碼。然而，sysmem 日後可能會新增其他程式碼，因此用戶端對任何失敗的狀態碼都應採用合理的預設處理方式。

要求

名稱	類型
`payload`	`NodeIsAlternateForRequest`

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

發布

在 fuchsia.sysmem2/BufferCollectionToken 管道中：

通常，參與者會將 BufferCollectionToken 轉換為 fuchsia.sysmem2/BufferCollection，但參與者可以改透過權杖傳送 Release (然後立即或稍後對伺服器關閉伺服器的回應而關閉管道)，如此可避免造成緩衝區收集失敗。如果沒有先前的 Release，關閉 BufferCollectionToken 用戶端端會導致緩衝區收集失敗。

在 fuchsia.sysmem2/BufferCollection 管道上：

根據預設，伺服器會在緩衝區收集失敗的情況下，處理 fuchsia.sysmem2/BufferCollection 用戶端端 (沒有 Release 前) 的意外關閉。其中一部分是加快關閉 VMO 控制代碼，以便在任何參與者失敗時收回記憶體。如果參與者想要徹底關閉 BufferCollection，而不導致緩衝區收集失敗，參與者可以在關閉 BufferCollection 用戶端之前傳送 Release。Release 可能會在 SetConstraints 之前或之後發生。如果 SetConstraints 之前，緩衝區集合不需要此節點的限制即可分配。如果 SetConstraints 之後，即使限制匯總時缺少 BufferCollection 連線，系統仍會保留並匯總限制條件。

在 fuchsia.sysmem2/BufferCollectionTokenGroup 管道：

根據預設，如果 BufferCollectionTokenGroup 用戶端結束 (沒有 Release 前) 的非預期關閉會觸發緩衝區收集作業，如要關閉 BufferCollectionTokenGroup 管道而不失敗緩衝區收集，請確認已傳送 AllChildrenPresent()，並在關閉 BufferCollectionTokenGroup 用戶端前傳送 Release。

如果 Release 早於 [fuchsia.sysmem2/BufferCollectionTokenGroup.AllChildrenPresent], the buffer collection will fail (triggered by reception of Releasewithout priorAllChildrenPresent). This is intentionally not analogous to how <a class='link' href='../fuchsia.sysmem2/'>fuchsia.sysmem2</a>/<a class='link' href='../fuchsia.sysmem2/#BufferCollection.Release'>BufferCollection.Release</a> without <a class='link' href='../fuchsia.sysmem2/'>fuchsia.sysmem2</a>/<a class='link' href='../fuchsia.sysmem2/#BufferCollection.SetConstraints'>BufferCollection.SetConstraints</a> first doesn't cause buffer collection failure. For a BufferCollectionTokenGroup, clean close requires AllChildrenPresent(if not already sent), thenRelease)，則請關閉用戶端。

如果 Release 在 AllChildrenPresent 之後，子項及其所有限制都會完整保留 (就像當 BufferCollectionTokenGroup 管道保持開啟時一樣)，且用戶端結束關閉不會觸發緩衝區收集失敗的情形。

在所有 fuchsia.sysmem2/Node 管道 (上述任一管道)：

為求簡潔，上述個別管道通訊協定段落會忽略 fuchsia.sysmem2/BufferCollectionToken.SetDispensable 或 fuchsia.sysmem2/BufferCollection.AttachToken 建立的個別失敗網域。如果用戶端意外關閉 (第一個未出現 Release)，且該用戶端位於故障網域下，則失敗網域不會失敗，但緩衝區收集本身會與失敗網域故障排除。這類故障網域可以巢狀結構，此時只有 Node 所在的內部失敗網域會失敗。

要求

<EMPTY>

SetConstraints

將 fuchsia.sysmem2/BufferCollectionConstraints 提供給緩衝區集合。

每個 fuchsia.sysmem2/BufferCollection 最多只能呼叫 fuchsia.sysmem2/BufferCollection.SetConstraints。

如要嘗試配置緩衝區分配，BufferCollection 用戶端的所有持有者都必須呼叫 SetConstraints，系統才能嘗試分配緩衝區。

要求 constraints 這些是傳送用戶端/參與者對緩衝區收集的限制。不必設定 constraints 欄位。如果未設定，用戶端不會設定任何實際的限制，但代表用戶端沒有可設定的限制條件。未設定 constraints 欄位的用戶端不會接收任何 VMO 控制，但仍能查看已分配的緩衝區數量，且仍可透過 buffer_index 參照緩衝區。

要求

名稱	類型
`payload`	`BufferCollectionSetConstraintsRequest`

SetDebugClientInfo

設定 Smem 可使用的目前用戶端資訊，協助診斷記憶體流失和配置延遲，等候參與者傳送 fuchsia.sysmem2/BufferCollection.SetConstraints。

這會為這個 fuchsia.sysmem2/Node 和由這個 Node 衍生的所有 Node 設定偵錯用戶端資訊，除非以 fuchsia.sysmem2/Allocator.SetDebugClientInfo 或後續的 fuchsia.sysmem2/Node.SetDebugClientInfo 覆寫。

每 Allocator Node.1.fuchsia.sysmem2 Allocator.SetDebugClientInfo fuchsia.sysmem2 fuchsia.sysmem2 Node.SetDebugClientInfo fuchsia.sysmem2

啟用詳細記錄功能時 (請參閱 SetVerboseLogging)，也能指出哪個用戶端先關閉管道，導致子樹狀結構失敗 (如果子樹狀結構的用途已經結束，這可能很正常，但如果情況比預期早一點，用戶管道專屬名稱有助於診斷 sysmem 的觀點造成最初失敗的位置)。

目前所有表格欄位均為必填。

要求 name 可以是任意字串，但目前的程序名稱 (請參閱 fsl::GetCurrentProcessName) 是不錯的預設值。
要求 id 可以是任意 ID，但目前的程序 ID (請參閱 fsl::GetCurrentProcessKoid) 是不錯的預設值。

要求

名稱	類型
`payload`	`NodeSetDebugClientInfoRequest`

SetDebugTimeoutLogDeadline

如果 sysmem 在建立新集合後的 5 秒內，未從所有用戶端看到 fuchsia.sysmem2/BufferCollection.SetConstraints，則 Sysmem 會記錄一則警告。

用戶端可呼叫此方法，在列印記錄時變更。如果有多個用戶端設定期限，系統將無法指定最終會生效的期限。

在大多數情況下，預設設定都能正常運作。

目前所有表格欄位均為必填。

要求 deadline 表示 sysmem 開始嘗試記錄警告的時間，除非所有限制在此日期前都有 sysmem。

要求

名稱	類型
`payload`	`NodeSetDebugTimeoutLogDeadlineRequest`

SetName

為這個緩衝區集合中的 VMO 設定名稱。

如果名稱不符合 ZX_MAX_NAME_LEN 中，vmo 本身的名稱會遭到截斷，以符合大小。vmo 的名稱會加上集合內的緩衝區索引後綴字串 (如果後置字串符合 ZX_MAX_NAME_LEN)。此處指定的名稱 (不含截斷) 會列於檢查資料中。

這個名稱只會影響設定名稱之後分配的 VMO，這項呼叫不會重新命名現有的 VMO。如果多個用戶端設定不同的名稱，則優先順序較大的值將採用。設定與之前名稱相同的新名稱並不會改變名稱。

目前所有表格欄位均為必填。

要求 priority 只有在這是第一個 SetName 或是 priority 晚於在此緩衝區集合的所有 Node 之前的 SetName 呼叫中，且超過任何先前的 priority 值時，才會設定名稱。
要求 name 在這個緩衝區集合底下建立的 VMO 名稱。

要求

名稱	類型
`payload`	`NodeSetNameRequest`

SetVerboseLogging

以便為緩衝區收集作業啟用詳細記錄功能。

詳細記錄包含透過每個用戶端 fuchsia.sysmem2/BufferCollection.SetConstraints 設定的限制，以及透過 fuchsia.sysmem2/Node.SetDebugClientInfo (或 Allocator.SetDebugClientInfo 的結構) 設定的限制。Node

額外記錄的用意是從效能觀點接受的，前提是這些記錄只對少量的緩衝區集合啟用。如果您並未追蹤錯誤我們不應傳送這則訊息

要求

<EMPTY>

SetWeak

將目前 fuchsia.sysmem2/Node 和在這則訊息後建立的所有子項 Node 設為微弱，這表示用戶端的 Node 用戶端 (或在這項訊息後建立的子項) 不足以保持分配的 VMO 有效。

所有從較弱的 Node 取得的 VMO 都為弱的 sysmem VMO。另請參閱 close_weak_asap。

只有在 Node 準備好進行分配前 (否則伺服器會關閉使用 ZX_ERR_BAD_STATE 的管道)，才允許這則訊息：

BufferCollectionToken：不限時間
BufferCollection：在 SetConstraints之前
BufferCollectionTokenGroup：在 AllChildrenPresent之前

目前還沒有將強力 Node 轉換為低強度的 Node，但用戶端可在分配前建立額外的 Node，並將額外的 Node 設為弱點，然後可能在稍後傳送 Release 並關閉用戶端強而有力的 Node，同時維持用戶端的較弱 Node。

沒有任何高強度 Node (以及) 強的 VMO 控制代碼會導致緩衝區收集失敗 (所有 Node 用戶端端都會看到 ZX_CHANNEL_PEER_CLOSED，而所有 close_weak_asap client_end 都會看到 ZX_EVENTPAIR_PEER_CLOSED)，但 Smem (刻意) 在所有 Node 都準備好要分配時才會發現這種情況。如要成功進行初始配置，分配時間至少需要一個強而有力的 Node，但在該用戶端收到 VMO 處理後，該用戶端就可以 BufferCollection.Release 並關閉用戶端，而不會造成這類型失敗。

這也意味著 fuchsia.sysmem2/Node.SetWeakOk，但不是含 for_children_also true 的 SetWeakOk (您可以視需要一併傳送)。

要求

<EMPTY>

SetWeakOk

這表示 sysmem 表示用戶端已準備好注意 close_weak_asap。

如果已傳送，這則訊息必須早於 fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated。

所有使用低強度 fuchsia.sysmem2/BufferCollection 的參與者都必須在 WaitForAllBuffersAllocated 之前傳送這則訊息，或者父項 Node 必須在 WaitForAllBuffersAllocated 之前傳送 fuchsia.sysmem2/Node.SetWeakOk，且 for_child_nodes_also 是 for_child_nodes_also，否則 WaitForAllBuffersAllocated 會觸發緩衝區收集失敗。

這些訊息是必要的，因為 sysmem VMO 的弱點未必是一事，因此較舊的用戶端不知道需要注意 close_weak_asap ZX_EVENTPAIR_PEER_CLOSED，並關閉所有剩餘的 sysmem 弱點 VMO 會急用處理。透過提供這則訊息並要求參與者表示接受該整體通訊協定的部分，我們可避免舊版用戶端傳送較弱的 VMO，且沒有任何方法讓 sysmem 在該 VMO 之後快速關閉該 VMO (或以每個緩衝區為基礎)。

不處理 close_weak_asap 且不會透過 WaitForAllBuffersAllocated 擷取任何 VMO 控制代碼的參與者，不需要傳送 SetWeakOk (也不需要讓父項 Node 傳送 SetWeakOk 為 for_child_nodes_also 的值)。不過，如果同一參與者擁有可擷取 VMO 的子項/委派，該子項/委派項目必須在 WaitForAllBuffersAllocated 前傳送 SetWeakOk。

要求 for_child_nodes_also 如果存在，且表示此節點在這則訊息後建立的直接子節點加上這些節點的所有子系，則會假設 SetWeakOk 是在這些節點上傳送。不包含在這個節點之前建立的任何子節點。這項設定為「固定式」，即使後續的 SetWeakOk 未將此佈林值設為 true，也不會重設伺服器端的布林值。如果這會導致參與者發生問題，請視情況在子權杖上，將 for_child_nodes_also 設為 true，並改為將 SetWeakOk 設為 true。只有在參與者確實承諾會同時遵循 close_weak_asap 對其自己的低強度 VMO 控制代碼，以及持有對應子項 Node 的參與者所持有的所有 VMO 處理不當時，參與者才應將 for_child_nodes_also 設為 true。設定 for_child_nodes_also 後，即使這些 sysmem1 Node 的用戶端無法直接連線至 SetWeakOk，或透過任何直接方法取得 close_weak_asap 相關資訊，使用 sysmem(1) 的子系 Node 可能較弱。這僅適用於這個 Node 的子項 (使用 sysmem(1))，不適用於這個 Node (如果是直接從 sysmem2 憑證轉換為 sysmem(1) 符記；除非這個 Node 的祖係指定的 for_child_nodes_also 為 true，否則無法分配。

要求

名稱	類型
`payload`	`NodeSetWeakOkRequest`

同步

確定在伺服器端收到先前的郵件。這在先前建立新符記的訊息之後特別實用，因為 sysmem 伺服器必須先知道憑證才能傳送給其他參與者。

對非有效權杖呼叫 fuchsia.sysmem2/BufferCollectionToken.Sync 會導致 Sync 永久停滯。請參閱 fuchsia.sysmem2/Allocator.ValidateBufferCollectionToken，以將每趟來回行程的費用降低惡意/偽造 fuchsia.sysmem2/BufferCollectionToken。另一個方法是將權杖傳遞至 fuchsia.sysmem2/Allocator/BindSharedCollection，並在交換 fuchsia.sysmem2/BufferCollection 管道時驗證權杖，而 fuchsia.sysmem2/BufferCollection.Sync

建立一或多個 fuchsia.sysmem2/BufferCollectionToken(啟動並完成 Sync) 後，接著可以安全地將 BufferCollectionToken 用戶端傳送給其他參與者。當其他參與者傳送給 fuchsia.sysmem2/Allocator.BindSharedCollection這種做法可以有效建立符記，同時避免不必要的來回行程。

其他選項包括等待每個 fuchsia.sysmem2/BufferCollectionToken.Duplicate 建立每個 fuchsia.sysmem2/BufferCollectionToken.Duplicate 分別完成的工作 (每次使用個別呼叫 Sync)，或是在憑證透過 fuchsia.sysmem2 Allocator.BindSharedCollection fuchsia.sysmem2 BufferCollectionToken.DuplicateSync

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_Sync_Result`

WaitForAllBuffersAllocated

等待系統分配所有緩衝區。

當分配到緩衝區時，這項 FIDL 呼叫就會完成；如果嘗試分配但失敗，則完成某些失敗的詳細資料。

系統會先發生以下情況，才能分配緩衝區：

必須為緩衝區集合的所有 fuchsia.sysmem2/BufferCollectionToken{FufferCollectionToken{BindSharedCollectionfuchsia.sysmem2 BufferCollection fuchsia.sysmem2 BufferCollection.AttachToken fuchsia.sysmem2 BufferCollectionToken.Release
緩衝區集合的所有 fuchsia.sysmem2/BufferCollection(要求) 必須傳送 fuchsia.sysmem2/BufferCollection.SetConstraints 或傳送給 fuchsia.sysmem2/BufferCollection.Release。

結果 buffer_collection_info。VMO 會處理和其他相關資訊。

錯誤 [fuchsia.sysmem2/Error.NO_MEMORY] 要求有效，但因資源耗盡而無法執行。
error [fuchsia.sysmem2/Error.PROTOCOL_DEVIATION] 要求格式錯誤。
error [fuchsia.sysmem2/Error.CONSTRAINTS_INTERSECTION_EMPTY] 要求有效，但因硬體限製而無法滿足要求。如果參與者有不相容的限制 (無意相隔的交集)，就可能發生這種情況。詳情請參閱記錄。若系統可能會將參與者視為非必要，請參閱 BufferCollectionTokenGroup。使用 fuchsia.sysmem2/BufferCollection.AttachToken 時，如果現有集合中的緩衝區不足以滿足附加權杖所設定的限制，以及衍生自附加權杖的任何權杖子樹狀結構，這個錯誤代碼就會是錯誤代碼。

要求

<EMPTY>

回應

名稱	類型
`payload`	`BufferCollection_WaitForAllBuffersAllocated_Result`

BufferCollectionToken

fuchsia.sysmem2/BufferCollectionToken 並不是緩衝區集合，但可以識別特定潛在的共用緩衝區集合，且可在緩衝區收集分配任何緩衝區之前，將該潛在共用緩衝區集合分配給其他參與者的方法。

這個通訊協定未使用 Epitaph，

我們會使用 BufferCollectionToken 的管道，而非單一 eventpair (配對)，因為這樣我們能夠偵測例如參與者在建立期間失敗等錯誤狀況。

新增時間：19 歲

CreateBufferCollectionTokenGroup

在一組符記中建立邏輯 OR，稱為 fuchsia.sysmem2/BufferCollectionTokenGroup。

大部分的 sysmem 用戶端和許多參與者不需要關注這則訊息或 BufferCollectionTokenGroup。然而，在某些情況下，參與者想嘗試加入一組委派參與者，但如果限制未成功結合，則返回不同的 (可能重疊) 一組委派參與者，以及/或改用要求較少的策略 (根據fuchisa.sysmem2/BufferCollectionConstraints)。在這種情況下，BufferCollectionTokenGroup 非常實用。

BufferCollectionTokenGroup 是用來在 N 個子項 fuchsia.sysmem2/BufferCollectionToken 之間建立 N OR 的值。匯總期間未選取的子項權杖會失敗 (關閉)，而潛在參與者的 BufferCollection 管道用戶端端點看到 PEER_CLOSED 時，應會注意到，以允許參與者清除最終未發生的推測用量 (這對於一般 BufferCollection 伺服器在失敗時關閉，或之後因無法分配邏輯緩衝區收集作業失敗而結束的推測)。

請參閱通訊協定 BufferCollectionTokenGroup 的留言。

凡是要套用至整個群組的 rights_attenuation_mask 或 AttachToken/SetDispensable，都可以使用 BufferCollectionToken 來實現，做為 BufferCollectionTokenGroup 的直接父項。

目前所有表格欄位均為必填。

要求 group_request。BufferCollectionTokenGroup 管道的伺服器端由 sysmem 處理。

要求

名稱	類型
`payload`	`BufferCollectionTokenCreateBufferCollectionTokenGroupRequest`

複製

從這個項目建立額外的 fuchsia.sysmem2/BufferCollectionToken，參照相同的緩衝區集合。

建立的憑證是 fuchsia.sysmem2/Node 層中這個憑證的子項。

這個方法可用來新增參與者，方法是將新建立的權杖轉移給其他參與者。

在效能敏感的情況下，這個單向訊息可用來取代雙向 fuchsia.sysmem2/BufferCollectionToken.DuplicateSync FIDL 呼叫，而在這類情況下，會無法等待 sysmem 回應 fuchsia.sysmem2/BufferCollectionToken.DuplicateSync，或是在所有用戶端需要複製這類程式碼時，就能輕鬆進行複製。

傳送一或多個 Duplicate 訊息，並在將新建立的子權杖傳送給其他參與者 (或其他 fuchsia.sysmem2/Allocator 管道) 前，用戶端必須傳送 fuchsia.sysmem2/Node.Sync 並等待 Sync 回應。Sync 呼叫可在權杖上發出，或在取得的 BufferCollection 上傳送這個權杖至 BindSharedCollection。兩者都可以確保伺服器會先知道透過 Duplicate 建立的權杖，然後其他參與者透過獨立的 Allocator 管道將權杖傳送至伺服器。

所有權杖都必須透過 fuchsia.sysmem2/Allocator.BindSharedCollection 或 fuchsia.sysmem2/Node.Release 來啟用，才能成功分配緩衝區。BufferCollection

目前所有表格欄位均為必填。

要求 rights_attenuation_mask。這個遮罩中的權限位元會是零，但可透過用戶端結尾的 token_request 取得的緩衝區 VMO 權限不會出現。這可讓發起人或中介者證明委派參與者俱備的權利。這不允許參與者取得參與者尚未擁有的權限。ZX_RIGHT_SAME_RIGHTS 值可用於指定不套用任何屬性。
- 下列 Rights_attenuation_mask 的值將不會生效：
  - ZX_RIGHT_SAME_RIGHTS (建議)
  - 0xFFFFFFFF (計算注意力遮罩時就很合理)
  - 0 (已淘汰 - 請勿使用 0 - 「ERROR」會列入記錄)
要求 token_request 是 BufferCollectionToken 管道的伺服器端。此管道的用戶端會在共用緩衝區集合中，做為另一個參與者。

要求

名稱	類型
`payload`	`BufferCollectionTokenDuplicateRequest`

DuplicateSync

從這個項目建立其他 fuchsia.sysmem2/BufferCollectionToken，參照相同的緩衝區集合。

已建立的權杖是 fuchsia.sysmem2/Node 層中這個權杖的子項。

這個方法可以將新建立的權杖轉移給其他參與者，藉此新增更多參與者。

系統會針對 rights_attenuation_masks 陣列中的每個項目傳回新的權杖。

如果呼叫的權杖可能因符記可能有惡意/不受信任的提供者而實際上為有效憑證，請考慮先使用 fuchsia.sysmem2/Allocator.ValidateBufferCollectionToken，而非若 fuchsia.sysmem2/BufferCollectionToken.DuplicateSync。

相較於 fuchsia.sysmem2/BufferCollectionToken.Duplicate，呼叫這個方法後不需要個別的 fuchsia.sysmem2/Node.Sync，因為此呼叫會包含同步步驟，但此呼叫期間會產生來回費用。

所有權杖都必須透過 fuchsia.sysmem2/Allocator.BindSharedCollection 或 fuchsia.sysmem2/Node.Release 來匯入 sysmem，以便成功分配 {fuchsia.sysmem2/Node.Release，以便成功分配緩衝區 (或在牽涉到 fuchsia.sysmem2 BufferCollectionToken.AttachToken

目前所有表格欄位均為必填。

要求 rights_attenuation_mask 在 rights_attenuation_masks 的每個項目中，只要是可透過對應回傳權杖取得的緩衝區 VMO 權利中將缺少為零的權利位元。讓發起人或中介者能提及參與者可用的權利。這不允許參與者取得參與者尚未擁有的權限。ZX_RIGHT_SAME_RIGHTS 值可用於指定不應套用剪輯設定。

回應 tokens 用戶端會使用每個新建立的權杖結束。

要求

名稱	類型
`payload`	`BufferCollectionTokenDuplicateSyncRequest`

回應

名稱	類型
`payload`	`BufferCollectionToken_DuplicateSync_Result`

GetBufferCollectionId

取得緩衝區集合 ID。fuchsia.sysmem2/Allocator.GetVmoInfo (以及集合內的 buffer_index) 也可取得此 ID。

回應 buffer_collection_id 每次啟動的每個緩衝區集合都有這個 ID。每個緩衝區都由 buffer_collection_id 和 buffer_index 各自識別。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_GetBufferCollectionId_Result`

GetNodeRef

由於這是 get 並非集合，因此在 GetNodeRef 和 IsAlternateFor 呼叫之間不需要 fuchsia.sysmem2/Node.Sync，即使兩個呼叫通常位於不同的管道上。

另請參閱 fuchsia.sysmem2/Node.IsAlternateFor。

目前所有表格欄位均為必填。

回應 node_ref 這個帳號代碼可在其他 Node 管道中的 IsAlternateFor 傳送，證明用戶端已從這個 Node 取得控制代碼。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_GetNodeRef_Result`

IsAlternateFor

檢查呼叫 fuchsia.sysmem2/Node 是否位於子樹狀結構中，是否位於共同父項 fuchsia.sysmem2/BufferCollectionTokenGroup 的不同子項權杖 (與傳入的 node_ref 有關)。

此呼叫旨在協助清除重複許可控制項，以及進行偵錯。

您必須使用 fuchsia.sysmem2/Node.GetNodeRef 取得 node_ref。

node_ref 可以是重複的控制代碼；您不必在每次呼叫 fuchsia.sysmem2/Node.IsAlternateFor 時呼叫 GetNodeRef。

目前所有表格欄位均為必填。

回應 is_alternate
- true：呼叫節點與 node_ref Node 之間共同的第一個父項節點為 BufferCollectionTokenGroup。這表示呼叫 Node 和 node_ref Node 時，不會同時套用兩者的限制，而 sysmem 會選擇其中一個以上的限制條件，因為這兩者絕不會同時套用。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有一個子項子樹狀結構造成限制匯總。
- false：在呼叫 Node 與 node_ref Node 之間共用的第一個父項節點不是 BufferCollectionTokenGroup。目前同屬共用的第一個父項節點為 BufferCollectionToken 或 BufferCollection (無論 Release 為何)。這表示，如果涉及的任何父項 BufferCollectionTokenGroup 同時選取兩個 Node，呼叫 Node 和 node_ref Node 在邏輯分配的限制匯總期間，可能會同時套用這兩項限制。在此情況下，沒有任何 BufferCollectionTokenGroup 會直接禁止兩個 Node 和其限制都經過匯總，但即使為 false，如果一個或兩個 Node 具有直接或間接父項 BufferCollectionTokenGroup，而子樹狀結構與包含呼叫 Node 或 node_ref Node 的子樹狀結構不同，系統可能仍會將其中一個或兩個 Node 排除。

錯誤 [fuchsia.sysmem2/Error.NOT_FOUND] node_ref 與呼叫 Node 的緩衝區集合並未建立關聯。另一個此錯誤的原因是 node_ref 是具備足夠權限的 zx.Handle.EVENT 控制代碼，但實際上並非從 GetNodeRef 取得的實際 node_ref。
錯誤 [fuchsia.sysmem2/Error.PROTOCOL_DEVIATION] 呼叫端傳遞並非 zx.Handle:EVENT 控制代碼的 node_ref，或者在真實的 node_ref 上沒有所需權限。
這個呼叫不會傳回其他失敗的狀態碼。然而，sysmem 日後可能會新增其他程式碼，因此用戶端對任何失敗的狀態碼都應採用合理的預設處理方式。

要求

名稱	類型
`payload`	`NodeIsAlternateForRequest`

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

發布

在 fuchsia.sysmem2/BufferCollectionToken 管道中：

在 fuchsia.sysmem2/BufferCollection 管道上：

在 fuchsia.sysmem2/BufferCollectionTokenGroup 管道：

在所有 fuchsia.sysmem2/Node 管道 (上述任一管道)：

要求

<EMPTY>

SetDebugClientInfo

設定 Smem 可使用的目前用戶端資訊，協助診斷記憶體流失和配置延遲，等候參與者傳送 fuchsia.sysmem2/BufferCollection.SetConstraints。

每 Allocator Node.1.fuchsia.sysmem2 Allocator.SetDebugClientInfo fuchsia.sysmem2 fuchsia.sysmem2 Node.SetDebugClientInfo fuchsia.sysmem2

目前所有表格欄位均為必填。

要求 name 可以是任意字串，但目前的程序名稱 (請參閱 fsl::GetCurrentProcessName) 是不錯的預設值。
要求 id 可以是任意 ID，但目前的程序 ID (請參閱 fsl::GetCurrentProcessKoid) 是不錯的預設值。

要求

名稱	類型
`payload`	`NodeSetDebugClientInfoRequest`

SetDebugTimeoutLogDeadline

如果 sysmem 在建立新集合後的 5 秒內，未從所有用戶端看到 fuchsia.sysmem2/BufferCollection.SetConstraints，則 Sysmem 會記錄一則警告。

用戶端可呼叫此方法，在列印記錄時變更。如果有多個用戶端設定期限，系統將無法指定最終會生效的期限。

在大多數情況下，預設設定都能正常運作。

目前所有表格欄位均為必填。

要求 deadline 表示 sysmem 開始嘗試記錄警告的時間，除非所有限制在此日期前都有 sysmem。

要求

名稱	類型
`payload`	`NodeSetDebugTimeoutLogDeadlineRequest`

SetDispensable

將這個 fuchsia.sysmem2/BufferCollectionToken 設為可供應。

當 BufferCollectionToken 轉換為 fuchsia.sysmem2/BufferCollection 時，可分送狀態也適用於 BufferCollection。

一般而言，如果用戶端關閉 fuchsia.sysmem2/BufferCollection 用戶端，但沒有先傳送 fuchsia.sysmem2/BufferCollection.Release，則BufferCollection fuchisa.sysmem2/Node 也會失敗，進而導致 sys1} 系統發生故障。fuchsia.sysmem2 Node相對來說，配置緩衝區後，可選擇的 Node 可能會失敗，而不會導致父項在 fuchsia.sysmem2/Node 層中出現失敗。

可支付的 Node 在進行緩衝區分配前，會連同父項一起參與限制匯總。如果可支付的 Node 在分配緩衝區前失敗，故障會傳播至可支配的 Node 父項。

分配緩衝區後，可供應的 Node (或可供應 Node 的任何子項) 失敗，不會傳播至可發放的 Node 父項。這類錯誤會從可支付 Node 的一般子項傳播至可分配的 Node。如果使用 fuchsia.sysmem2/BufferCollection.AttachToken 附加子項，或者如果子項可支付且在分配後發生失敗，則系統會禁止子項與父項連線。

如果參與者需要提供限制，則可以使用可支付的 Node，但在緩衝區分配到緩衝區後，參與者可能會失敗，且不會造成父項 Node 視角的緩衝區收集失敗。

相反地，BufferCollection.AttachToken 可以用來建立 BufferCollectionToken，該 BufferCollectionToken 不會參與父項 Node 的限制匯總，而且如果失敗，父項 Node 就不會傳播至父項 Node，且如果潛在延遲提供限制，父項 Node 就無法完成其緩衝區分配。

在某些情況下，發起人 (使用 fuchsia.sysmem2/Allocator.AllocateSharedCollection 的根 Node 建立者) 可能會在某些情境中，為參與者的第一個例項使用可分配的 Node，之後如果該參與者的第一個例項失敗，就會由 BufferCollectionToken 為該參與者建立新的第二個例項。AttachToken

一般而言，用戶端會先在 BufferCollectionToken 上 SetDispensable，然後再將可分配的 BufferCollectionToken 傳送給委派參與者。由於 SetDispensable 會防止將子項 Node 傳播至父項 Node，因此如果用戶端在透過用戶端保留父項 Node 失敗時指出子項失敗，可能需要透過其他方式發現失敗。如果其他方法都無法使用/方便，用戶端可以改為保留可取用的 Node，並在其下建立一個子項 Node，以傳送給委派參與者，並保留此 Node，以透過此 Node 的 ZX_CHANNEL_PEER_CLOSED 信號啟動根子樹狀結構故障，然後採取適當的動作 (例如，透過委派的 SX 呼叫啟動 Sys 的新權杖，或以手動方式升級 Syb)。NodeBufferCollectionTokenfuchsia.sysmem2

雖然 BufferCollectionTokenGroup Node 的直接子項可以 (且可能有幫助) 使用 SetDispensable，但之後無法使用 AttachToken 將失敗的可分端 Node，替換成使用 AttachToken 的新權杖 (因為群組中沒有 AttachToken)。BufferCollectionTokenGroup如要在此情況下啟用 AttachToken 取代功能，請改為建立其他不可支付的權杖，這是群組的直接子項，並將現有的可支付權杖設為額外權杖的子項。如此一來，做為群組直接子項的額外權杖就會擁有 BufferCollection.AttachToken，可用於取代失敗的可支付權杖。

對現有權杖上的 SetDispensable 為冪等。

要求

<EMPTY>

SetName

為這個緩衝區集合中的 VMO 設定名稱。

目前所有表格欄位均為必填。

要求 priority 只有在這是第一個 SetName 或是 priority 晚於在此緩衝區集合的所有 Node 之前的 SetName 呼叫中，且超過任何先前的 priority 值時，才會設定名稱。
要求 name 在這個緩衝區集合底下建立的 VMO 名稱。

要求

名稱	類型
`payload`	`NodeSetNameRequest`

SetVerboseLogging

以便為緩衝區收集作業啟用詳細記錄功能。

額外記錄的用意是從效能觀點接受的，前提是這些記錄只對少量的緩衝區集合啟用。如果您並未追蹤錯誤我們不應傳送這則訊息

要求

<EMPTY>

SetWeak

所有從較弱的 Node 取得的 VMO 都為弱的 sysmem VMO。另請參閱 close_weak_asap。

只有在 Node 準備好進行分配前 (否則伺服器會關閉使用 ZX_ERR_BAD_STATE 的管道)，才允許這則訊息：

BufferCollectionToken：不限時間
BufferCollection：在 SetConstraints之前
BufferCollectionTokenGroup：在 AllChildrenPresent之前

這也意味著 fuchsia.sysmem2/Node.SetWeakOk，但不是含 for_children_also true 的 SetWeakOk (您可以視需要一併傳送)。

要求

<EMPTY>

SetWeakOk

這表示 sysmem 表示用戶端已準備好注意 close_weak_asap。

如果已傳送，這則訊息必須早於 fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated。

要求 for_child_nodes_also 如果存在，且表示此節點在這則訊息後建立的直接子節點加上這些節點的所有子系，則會假設 SetWeakOk 是在這些節點上傳送。不包含在這個節點之前建立的任何子節點。這項設定為「固定式」，即使後續的 SetWeakOk 未將此佈林值設為 true，也不會重設伺服器端的布林值。如果這會導致參與者發生問題，請視情況在子權杖上，將 for_child_nodes_also 設為 true，並改為將 SetWeakOk 設為 true。只有在參與者確實承諾會同時遵循 close_weak_asap 對其自己的低強度 VMO 控制代碼，以及持有對應子項 Node 的參與者所持有的所有 VMO 處理不當時，參與者才應將 for_child_nodes_also 設為 true。設定 for_child_nodes_also 後，即使這些 sysmem1 Node 的用戶端無法直接連線至 SetWeakOk，或透過任何直接方法取得 close_weak_asap 相關資訊，使用 sysmem(1) 的子系 Node 可能較弱。這僅適用於這個 Node 的子項 (使用 sysmem(1))，不適用於這個 Node (如果是直接從 sysmem2 憑證轉換為 sysmem(1) 符記；除非這個 Node 的祖係指定的 for_child_nodes_also 為 true，否則無法分配。

要求

名稱	類型
`payload`	`NodeSetWeakOkRequest`

同步

確定在伺服器端收到先前的郵件。這在先前建立新符記的訊息之後特別實用，因為 sysmem 伺服器必須先知道憑證才能傳送給其他參與者。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_Sync_Result`

BufferCollectionTokenGroup

sysmem 實作與分配 / 邏輯分配的邏輯 / 概念模型一致，如下所示：

像往常一樣，邏輯分配會考量根層級和所有連至根 (且只連接根層級) 的節點，且這些節點不會傳送以 fuchsia.sysmem2/BufferCollection.AttachToken 建立的 fuchsia.sysmem2/Node，或位於 AttachToken Node 且具有其他未連線其他大眾運輸樹狀結構的所有 Node() 子樹狀結構。AttachToken這稱為經修剪的邏輯配置子樹狀結構，或為短的修剪子樹狀結構。

在限制匯總期間，每個 fuchsia.sysmem2/BufferCollectionTokenGroup 都會在其直接子項中選取單一子項 Node。其餘子項的其餘部分似乎會失敗邏輯分配，而所選子項可能會成功。

當整體邏輯配置的子樹狀結構中有多個 BufferCollectionTokenGroup 時，兩個群組的相對優先順序等同於樹狀結構的 DFS 預購疊代作業中的排序，父項的優先順序高於子項，且讓子項的優先順序高於右子項。

選取群組中的特定子項時 (無論是在限制匯總期間，還是做為最終選取的情況下)，該群組的其他子項非選取項目會「隱藏」這些未選取子項底下的任何其他群組。

在邏輯分配中，系統會嘗試先暫時選取優先順序最高的群組中的子項 0，以及下一個優先順序最高的群組，但不由臨時選取範圍隱藏的子項 0 等。

如果匯總嘗試失敗，則會嘗試以所有相同群組的一般 0 子項進行匯總，但優先順序最低的非隱藏群組除外，這會佈建其序對 1 子項 (然後是子項 2 依此類推)。如果新優先順序最低的群組為取消隱藏以做為佈建的選擇更新，則新取消隱藏的最低優先順序群組會按順序考慮其所有子項，之後才會變更先前最低優先順序群組中的臨時選取。因此，這相當於依計數方式，將所有可能選項組合的系統化列舉，分別更新優先順序最低的群組，以及優先順序最高的群組。在不變更結果的情況下，我們可以略過多餘/相等的組合，不需要實際嘗試所有組合的匯總。

嘗試對列舉的非相等選項組合進行限制的匯總作業會持續，直到以下情況發生為止：(a) 整體邏輯配置失敗時，所有匯總嘗試失敗，或 (b) 直到嘗試匯總成功為止，在此情況下，系統會視需要進行緩衝區分配 (如果這是整體根層級 Node 經修剪的子樹狀結構)。如果根據第一項成功的限制匯總失敗的緩衝區分配失敗，整體邏輯分配就會失敗 (即沒有重新進行緩衝區分配的重試 / 重試作業)。如果緩衝區分配成功 (或由於未包含根層級的已裁剪子樹狀結構而不需要)，邏輯配置就會成功。

如果這種優先處理機制無法合理對您使用系統化的系統使用，請立即與 sysmem 團隊聯絡，討論我們可能新增的方法來滿足您的需求。

請避免為每個邏輯分配建立大量 BufferCollectionTokenGroup，尤其是整體子項數量較多時，尤其是在合理情況下，匯總通常會使用序數 0 子項失敗，並可能帶有後續的子項。Sysmem 透過將邏輯配置的失敗範圍超過特定 (相當高，但非很大) 的分類群組子項組合/選擇數量上限，降低可能相當耗時的複雜性。我們預期更進階 (且更複雜的) 緩解措施是必要或將會增加的複雜性。如果超出上限或預期會達到上限，請與 sysmem 團隊聯絡，討論可能的選項。

在可行情況下，建議您在單一 fuchsia.sysmem2/BufferCollectionConstraints 中使用多個 fuchsia.sysmem2/ImageFormatConstraints (當參與者只表達能與多個 fuchsia.images2/PixelFormat 搭配使用的功能，並搭配 sys2em/ 系統支援的 sys2em} 使用這些參與者)。PixelFormat

類似於 fuchsia.sysmem2/BufferCollectionToken 和 {fuchsia.sysmem2/BufferCollection，將 BufferCollectionTokenGroup 管道關閉。/Node.Release 將出現緩衝區收集失敗。BufferCollectionTokenGroupfuchsia.sysmem2 BufferCollectionToken.SetDispensable fuchsia.sysmem2 BufferCollection.AttachToken

這個通訊協定未使用 Epitaph，

新增時間：19 歲

AllChildrenPresent

表示不會再建立任何子項。

建立所有子項後，用戶端應傳送 fuchsia.sysmem2/BufferCollectionTokenGroup.AllChildrenPresent 以通知 sysmem 不會再建立其他子項，讓 sysmem 知道何時可以啟動匯總限制。

不允許在 AllChildrenPresent 後傳送 CreateChild；這會導致群組的子樹狀結構失敗並關閉連線。

如果系統必須傳送 fuchsia.sysmem2/Node.Release，則應在 AllChildrenPresent 之後傳送，否則群組子樹狀結構的失敗情形就會觸發。這與刻意不類似 Release 之前的 fuchsia.sysmem2/BufferCollection.SetConstraints 不會造成子樹狀結構錯誤。

要求

<EMPTY>

CreateChild

建立子項 fuchsia.sysmem2/BufferCollectionToken。進行分配 (或邏輯分配) 時，只會選取一個子項 (包括子項)。

將這個權杖的用戶端端傳遞至 fuchsia.sysmem2/Allocator.BindSharedCollection，必須在 fuchsia.sysmem2/BufferCollectionTokenGroup.CreateChild 後完成 fuchsia.sysmem2/Node.Sync。或者，用戶端可以使用 fuchsia.sysmem2/BufferCollectionTokenGroup.CreateChildrenSync，基本上包含 Sync。

不允許在 AllChildrenPresent 後傳送 CreateChild；這會導致群組的子樹狀結構失敗並關閉連線。

所有子項都建立完畢後，請傳送 AllChildrenPresent。

要求 token_request 新權杖管道的伺服器結尾。
要求 rights_attenuation_mask 如果為 ZX_RIGHT_SAME_RIGHTS，已建立的符記可讓持有者取得與緩衝區 (群組父項權杖) 相同的權利。如果值不是 ZX_RIGHT_SAME_RIGHTS，系統會將該值解讀為位元遮罩 (0 位元)，確保這些權利受到關注，因此 0xFFFFFFFF 是 ZX_RIGHT_SAME_RIGHTS 的同義詞。不允許使用 0 值，並刻意造成子樹狀結構故障。

要求

名稱	類型
`payload`	`BufferCollectionTokenGroupCreateChildRequest`

CreateChildrenSync

以同步方式一次建立一或多個子權杖。相較於 fuchsia.sysmem2/BufferCollectionTokenGroup.CreateChild，則必須先取得 fuchsia.sysmem2/Node.Sync，才能將傳回權杖的用戶端端傳送至 fuchsia.sysmem2/Allocator/BindSharedCollection。

索引下限的子符記優先順序高於索引值較高的子符記 (較早嘗試)。

根據所有子項權杖，成功的匯總作業會在所有已建立的子項中選擇一個子項 (也就是在可能多次呼叫 fuchsia.sysmem2/BufferCollectionTokenGroup.CreateChild 和 fuchsia.sysmem2/BufferCollectionTokenGroup.CreateChildrenSync 的所有子項)。

每個群組允許的子項總數上限和整體樹狀結構中的節點總數 (來自根層級) 有上限，無法透過這些通訊協定設定。

在不允許 AllChildrenPresent 後傳送 CreateChildrenSync；這會導致群組的子樹狀結構失敗並關閉連線。

所有子項都建立完畢後，請傳送 AllChildrenPresent。

要求 rights_attentuation_masks rights_attentuation_masks 的大小會決定已建立的子符記數量。ZX_RIGHT_SAME_RIGHTS 值並不具備任何權利。 0xFFFFFFFF 的值是 ZX_RIGHT_SAME_RIGHTS 的同義詞。如果是其他值，遮罩中的每個 0 位元都代表該值。

回應 tokens 已建立的子權杖。

要求

名稱	類型
`payload`	`BufferCollectionTokenGroupCreateChildrenSyncRequest`

回應

名稱	類型
`payload`	`BufferCollectionTokenGroup_CreateChildrenSync_Result`

GetBufferCollectionId

取得緩衝區集合 ID。fuchsia.sysmem2/Allocator.GetVmoInfo (以及集合內的 buffer_index) 也可取得此 ID。

回應 buffer_collection_id 每次啟動的每個緩衝區集合都有這個 ID。每個緩衝區都由 buffer_collection_id 和 buffer_index 各自識別。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_GetBufferCollectionId_Result`

GetNodeRef

由於這是 get 並非集合，因此在 GetNodeRef 和 IsAlternateFor 呼叫之間不需要 fuchsia.sysmem2/Node.Sync，即使兩個呼叫通常位於不同的管道上。

另請參閱 fuchsia.sysmem2/Node.IsAlternateFor。

目前所有表格欄位均為必填。

回應 node_ref 這個帳號代碼可在其他 Node 管道中的 IsAlternateFor 傳送，證明用戶端已從這個 Node 取得控制代碼。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_GetNodeRef_Result`

IsAlternateFor

檢查呼叫 fuchsia.sysmem2/Node 是否位於子樹狀結構中，是否位於共同父項 fuchsia.sysmem2/BufferCollectionTokenGroup 的不同子項權杖 (與傳入的 node_ref 有關)。

此呼叫旨在協助清除重複許可控制項，以及進行偵錯。

您必須使用 fuchsia.sysmem2/Node.GetNodeRef 取得 node_ref。

node_ref 可以是重複的控制代碼；您不必在每次呼叫 fuchsia.sysmem2/Node.IsAlternateFor 時呼叫 GetNodeRef。

目前所有表格欄位均為必填。

回應 is_alternate
- true：呼叫節點與 node_ref Node 之間共同的第一個父項節點為 BufferCollectionTokenGroup。這表示呼叫 Node 和 node_ref Node 時，不會同時套用兩者的限制，而 sysmem 會選擇其中一個以上的限制條件，因為這兩者絕不會同時套用。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有一個子項子樹狀結構造成限制匯總。
- false：在呼叫 Node 與 node_ref Node 之間共用的第一個父項節點不是 BufferCollectionTokenGroup。目前同屬共用的第一個父項節點為 BufferCollectionToken 或 BufferCollection (無論 Release 為何)。這表示，如果涉及的任何父項 BufferCollectionTokenGroup 同時選取兩個 Node，呼叫 Node 和 node_ref Node 在邏輯分配的限制匯總期間，可能會同時套用這兩項限制。在此情況下，沒有任何 BufferCollectionTokenGroup 會直接禁止兩個 Node 和其限制都經過匯總，但即使為 false，如果一個或兩個 Node 具有直接或間接父項 BufferCollectionTokenGroup，而子樹狀結構與包含呼叫 Node 或 node_ref Node 的子樹狀結構不同，系統可能仍會將其中一個或兩個 Node 排除。

錯誤 [fuchsia.sysmem2/Error.NOT_FOUND] node_ref 與呼叫 Node 的緩衝區集合並未建立關聯。另一個此錯誤的原因是 node_ref 是具備足夠權限的 zx.Handle.EVENT 控制代碼，但實際上並非從 GetNodeRef 取得的實際 node_ref。
錯誤 [fuchsia.sysmem2/Error.PROTOCOL_DEVIATION] 呼叫端傳遞並非 zx.Handle:EVENT 控制代碼的 node_ref，或者在真實的 node_ref 上沒有所需權限。
這個呼叫不會傳回其他失敗的狀態碼。然而，sysmem 日後可能會新增其他程式碼，因此用戶端對任何失敗的狀態碼都應採用合理的預設處理方式。

要求

名稱	類型
`payload`	`NodeIsAlternateForRequest`

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

發布

在 fuchsia.sysmem2/BufferCollectionToken 管道中：

在 fuchsia.sysmem2/BufferCollection 管道上：

在 fuchsia.sysmem2/BufferCollectionTokenGroup 管道：

在所有 fuchsia.sysmem2/Node 管道 (上述任一管道)：

要求

<EMPTY>

SetDebugClientInfo

設定 Smem 可使用的目前用戶端資訊，協助診斷記憶體流失和配置延遲，等候參與者傳送 fuchsia.sysmem2/BufferCollection.SetConstraints。

每 Allocator Node.1.fuchsia.sysmem2 Allocator.SetDebugClientInfo fuchsia.sysmem2 fuchsia.sysmem2 Node.SetDebugClientInfo fuchsia.sysmem2

目前所有表格欄位均為必填。

要求 name 可以是任意字串，但目前的程序名稱 (請參閱 fsl::GetCurrentProcessName) 是不錯的預設值。
要求 id 可以是任意 ID，但目前的程序 ID (請參閱 fsl::GetCurrentProcessKoid) 是不錯的預設值。

要求

名稱	類型
`payload`	`NodeSetDebugClientInfoRequest`

SetDebugTimeoutLogDeadline

如果 sysmem 在建立新集合後的 5 秒內，未從所有用戶端看到 fuchsia.sysmem2/BufferCollection.SetConstraints，則 Sysmem 會記錄一則警告。

用戶端可呼叫此方法，在列印記錄時變更。如果有多個用戶端設定期限，系統將無法指定最終會生效的期限。

在大多數情況下，預設設定都能正常運作。

目前所有表格欄位均為必填。

要求 deadline 表示 sysmem 開始嘗試記錄警告的時間，除非所有限制在此日期前都有 sysmem。

要求

名稱	類型
`payload`	`NodeSetDebugTimeoutLogDeadlineRequest`

SetName

為這個緩衝區集合中的 VMO 設定名稱。

目前所有表格欄位均為必填。

要求 priority 只有在這是第一個 SetName 或是 priority 晚於在此緩衝區集合的所有 Node 之前的 SetName 呼叫中，且超過任何先前的 priority 值時，才會設定名稱。
要求 name 在這個緩衝區集合底下建立的 VMO 名稱。

要求

名稱	類型
`payload`	`NodeSetNameRequest`

SetVerboseLogging

以便為緩衝區收集作業啟用詳細記錄功能。

額外記錄的用意是從效能觀點接受的，前提是這些記錄只對少量的緩衝區集合啟用。如果您並未追蹤錯誤我們不應傳送這則訊息

要求

<EMPTY>

SetWeak

所有從較弱的 Node 取得的 VMO 都為弱的 sysmem VMO。另請參閱 close_weak_asap。

只有在 Node 準備好進行分配前 (否則伺服器會關閉使用 ZX_ERR_BAD_STATE 的管道)，才允許這則訊息：

BufferCollectionToken：不限時間
BufferCollection：在 SetConstraints之前
BufferCollectionTokenGroup：在 AllChildrenPresent之前

這也意味著 fuchsia.sysmem2/Node.SetWeakOk，但不是含 for_children_also true 的 SetWeakOk (您可以視需要一併傳送)。

要求

<EMPTY>

SetWeakOk

這表示 sysmem 表示用戶端已準備好注意 close_weak_asap。

如果已傳送，這則訊息必須早於 fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated。

要求 for_child_nodes_also 如果存在，且表示此節點在這則訊息後建立的直接子節點加上這些節點的所有子系，則會假設 SetWeakOk 是在這些節點上傳送。不包含在這個節點之前建立的任何子節點。這項設定為「固定式」，即使後續的 SetWeakOk 未將此佈林值設為 true，也不會重設伺服器端的布林值。如果這會導致參與者發生問題，請視情況在子權杖上，將 for_child_nodes_also 設為 true，並改為將 SetWeakOk 設為 true。只有在參與者確實承諾會同時遵循 close_weak_asap 對其自己的低強度 VMO 控制代碼，以及持有對應子項 Node 的參與者所持有的所有 VMO 處理不當時，參與者才應將 for_child_nodes_also 設為 true。設定 for_child_nodes_also 後，即使這些 sysmem1 Node 的用戶端無法直接連線至 SetWeakOk，或透過任何直接方法取得 close_weak_asap 相關資訊，使用 sysmem(1) 的子系 Node 可能較弱。這僅適用於這個 Node 的子項 (使用 sysmem(1))，不適用於這個 Node (如果是直接從 sysmem2 憑證轉換為 sysmem(1) 符記；除非這個 Node 的祖係指定的 for_child_nodes_also 為 true，否則無法分配。

要求

名稱	類型
`payload`	`NodeSetWeakOkRequest`

同步

確定在伺服器端收到先前的郵件。這在先前建立新符記的訊息之後特別實用，因為 sysmem 伺服器必須先知道憑證才能傳送給其他參與者。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_Sync_Result`

節點

此通訊協定是樹狀結構中由建立 fuchsia.sysmem2/BufferCollectionToken 建立和建立 fuchsia.sysmem2/BufferCollectionTokenGroup 建立的所有節點的父項通訊協定，包括 fuchsia.sysmem2/BufferCollectionToken(BufferCollectionToken fuchsia.sysmem2 BufferCollection

這個通訊協定未使用 Epitaph，

新增時間：19 歲

GetBufferCollectionId

取得緩衝區集合 ID。fuchsia.sysmem2/Allocator.GetVmoInfo (以及集合內的 buffer_index) 也可取得此 ID。

回應 buffer_collection_id 每次啟動的每個緩衝區集合都有這個 ID。每個緩衝區都由 buffer_collection_id 和 buffer_index 各自識別。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_GetBufferCollectionId_Result`

GetNodeRef

由於這是 get 並非集合，因此在 GetNodeRef 和 IsAlternateFor 呼叫之間不需要 fuchsia.sysmem2/Node.Sync，即使兩個呼叫通常位於不同的管道上。

另請參閱 fuchsia.sysmem2/Node.IsAlternateFor。

目前所有表格欄位均為必填。

回應 node_ref 這個帳號代碼可在其他 Node 管道中的 IsAlternateFor 傳送，證明用戶端已從這個 Node 取得控制代碼。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_GetNodeRef_Result`

IsAlternateFor

檢查呼叫 fuchsia.sysmem2/Node 是否位於子樹狀結構中，是否位於共同父項 fuchsia.sysmem2/BufferCollectionTokenGroup 的不同子項權杖 (與傳入的 node_ref 有關)。

此呼叫旨在協助清除重複許可控制項，以及進行偵錯。

您必須使用 fuchsia.sysmem2/Node.GetNodeRef 取得 node_ref。

node_ref 可以是重複的控制代碼；您不必在每次呼叫 fuchsia.sysmem2/Node.IsAlternateFor 時呼叫 GetNodeRef。

目前所有表格欄位均為必填。

回應 is_alternate
- true：呼叫節點與 node_ref Node 之間共同的第一個父項節點為 BufferCollectionTokenGroup。這表示呼叫 Node 和 node_ref Node 時，不會同時套用兩者的限制，而 sysmem 會選擇其中一個以上的限制條件，因為這兩者絕不會同時套用。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有一個子項子樹狀結構造成限制匯總。
- false：在呼叫 Node 與 node_ref Node 之間共用的第一個父項節點不是 BufferCollectionTokenGroup。目前同屬共用的第一個父項節點為 BufferCollectionToken 或 BufferCollection (無論 Release 為何)。這表示，如果涉及的任何父項 BufferCollectionTokenGroup 同時選取兩個 Node，呼叫 Node 和 node_ref Node 在邏輯分配的限制匯總期間，可能會同時套用這兩項限制。在此情況下，沒有任何 BufferCollectionTokenGroup 會直接禁止兩個 Node 和其限制都經過匯總，但即使為 false，如果一個或兩個 Node 具有直接或間接父項 BufferCollectionTokenGroup，而子樹狀結構與包含呼叫 Node 或 node_ref Node 的子樹狀結構不同，系統可能仍會將其中一個或兩個 Node 排除。

錯誤 [fuchsia.sysmem2/Error.NOT_FOUND] node_ref 與呼叫 Node 的緩衝區集合並未建立關聯。另一個此錯誤的原因是 node_ref 是具備足夠權限的 zx.Handle.EVENT 控制代碼，但實際上並非從 GetNodeRef 取得的實際 node_ref。
錯誤 [fuchsia.sysmem2/Error.PROTOCOL_DEVIATION] 呼叫端傳遞並非 zx.Handle:EVENT 控制代碼的 node_ref，或者在真實的 node_ref 上沒有所需權限。
這個呼叫不會傳回其他失敗的狀態碼。然而，sysmem 日後可能會新增其他程式碼，因此用戶端對任何失敗的狀態碼都應採用合理的預設處理方式。

要求

名稱	類型
`payload`	`NodeIsAlternateForRequest`

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

發布

在 fuchsia.sysmem2/BufferCollectionToken 管道中：

在 fuchsia.sysmem2/BufferCollection 管道上：

在 fuchsia.sysmem2/BufferCollectionTokenGroup 管道：

在所有 fuchsia.sysmem2/Node 管道 (上述任一管道)：

要求

<EMPTY>

SetDebugClientInfo

設定 Smem 可使用的目前用戶端資訊，協助診斷記憶體流失和配置延遲，等候參與者傳送 fuchsia.sysmem2/BufferCollection.SetConstraints。

每 Allocator Node.1.fuchsia.sysmem2 Allocator.SetDebugClientInfo fuchsia.sysmem2 fuchsia.sysmem2 Node.SetDebugClientInfo fuchsia.sysmem2

目前所有表格欄位均為必填。

要求 name 可以是任意字串，但目前的程序名稱 (請參閱 fsl::GetCurrentProcessName) 是不錯的預設值。
要求 id 可以是任意 ID，但目前的程序 ID (請參閱 fsl::GetCurrentProcessKoid) 是不錯的預設值。

要求

名稱	類型
`payload`	`NodeSetDebugClientInfoRequest`

SetDebugTimeoutLogDeadline

如果 sysmem 在建立新集合後的 5 秒內，未從所有用戶端看到 fuchsia.sysmem2/BufferCollection.SetConstraints，則 Sysmem 會記錄一則警告。

用戶端可呼叫此方法，在列印記錄時變更。如果有多個用戶端設定期限，系統將無法指定最終會生效的期限。

在大多數情況下，預設設定都能正常運作。

目前所有表格欄位均為必填。

要求 deadline 表示 sysmem 開始嘗試記錄警告的時間，除非所有限制在此日期前都有 sysmem。

要求

名稱	類型
`payload`	`NodeSetDebugTimeoutLogDeadlineRequest`

SetName

為這個緩衝區集合中的 VMO 設定名稱。

目前所有表格欄位均為必填。

要求 priority 只有在這是第一個 SetName 或是 priority 晚於在此緩衝區集合的所有 Node 之前的 SetName 呼叫中，且超過任何先前的 priority 值時，才會設定名稱。
要求 name 在這個緩衝區集合底下建立的 VMO 名稱。

要求

名稱	類型
`payload`	`NodeSetNameRequest`

SetVerboseLogging

以便為緩衝區收集作業啟用詳細記錄功能。

額外記錄的用意是從效能觀點接受的，前提是這些記錄只對少量的緩衝區集合啟用。如果您並未追蹤錯誤我們不應傳送這則訊息

要求

<EMPTY>

SetWeak

所有從較弱的 Node 取得的 VMO 都為弱的 sysmem VMO。另請參閱 close_weak_asap。

只有在 Node 準備好進行分配前 (否則伺服器會關閉使用 ZX_ERR_BAD_STATE 的管道)，才允許這則訊息：

BufferCollectionToken：不限時間
BufferCollection：在 SetConstraints之前
BufferCollectionTokenGroup：在 AllChildrenPresent之前

這也意味著 fuchsia.sysmem2/Node.SetWeakOk，但不是含 for_children_also true 的 SetWeakOk (您可以視需要一併傳送)。

要求

<EMPTY>

SetWeakOk

這表示 sysmem 表示用戶端已準備好注意 close_weak_asap。

如果已傳送，這則訊息必須早於 fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated。

要求 for_child_nodes_also 如果存在，且表示此節點在這則訊息後建立的直接子節點加上這些節點的所有子系，則會假設 SetWeakOk 是在這些節點上傳送。不包含在這個節點之前建立的任何子節點。這項設定為「固定式」，即使後續的 SetWeakOk 未將此佈林值設為 true，也不會重設伺服器端的布林值。如果這會導致參與者發生問題，請視情況在子權杖上，將 for_child_nodes_also 設為 true，並改為將 SetWeakOk 設為 true。只有在參與者確實承諾會同時遵循 close_weak_asap 對其自己的低強度 VMO 控制代碼，以及持有對應子項 Node 的參與者所持有的所有 VMO 處理不當時，參與者才應將 for_child_nodes_also 設為 true。設定 for_child_nodes_also 後，即使這些 sysmem1 Node 的用戶端無法直接連線至 SetWeakOk，或透過任何直接方法取得 close_weak_asap 相關資訊，使用 sysmem(1) 的子系 Node 可能較弱。這僅適用於這個 Node 的子項 (使用 sysmem(1))，不適用於這個 Node (如果是直接從 sysmem2 憑證轉換為 sysmem(1) 符記；除非這個 Node 的祖係指定的 for_child_nodes_also 為 true，否則無法分配。

要求

名稱	類型
`payload`	`NodeSetWeakOkRequest`

同步

確定在伺服器端收到先前的郵件。這在先前建立新符記的訊息之後特別實用，因為 sysmem 伺服器必須先知道憑證才能傳送給其他參與者。

要求

<EMPTY>

回應

名稱	類型
`payload`	`Node_Sync_Result`

結構化

BufferCollection_CheckAllBuffersAllocated_Response

<EMPTY>

Node_Sync_Response

<EMPTY>

PixelFormatAndModifier

欄位類型說明預設

pixel_format

fuchsia.images2/PixelFormat

當參與者在向 sysmem 的訊息中指定時，這可以是參與者接受的任何 PixelFormat 值。不允許指定 kInvalid。

如果參與者需要指定 ImageFormatConstraints，且不限制 pixel_format，參與者可以指定 fuchsia.images2/PixelFormat.DO_NOT_CARE。

無預設

pixel_format_modifier

fuchsia.images2/PixelFormatModifier

特定修飾符 (並非只有旗標) 或 FORMAT_MODIFIER_DO_NOT_CARE，源自 fuchsia.images2 format_modifier.fidl 定義的一組值。

無預設

ENUMS

CoherencyDomain 彈性

類型：uint32

INACCESSIBLE 僅適用於無法在 CPU 無法存取緩衝區的情況。

即使可能讓裝置 (實體或虛擬) 將資料從 INACCESSIBLE 緩衝區複製到 CPU 中可見的緩衝區，無法從 CPU 連線至的裝置本機記憶體也會是 CoherencyDomain INACCESSIBLE。換句話說，INACCESSIBLE 並不一定能保證安全，但安全的環境則代表無法存取。

CPU 表示生產端必須確保取用端能使用 CPU 讀取產生的資料，而取用者不需要進行生產者尚未執行 (需要) 的額外快取作業。

RAM 代表生產端必須確保產生的資料完全位於 RAM 中，不會有任何髒汙的 CPU 快取行，且取用端必須先撤銷 (或清除及撤銷) CPU 快取，才能使用 CPU 讀取資料。當所有存取都透過 HW DMA 進行存取時，RAM 網域可能比 CPU 網域快，因為在此情況下不需要 CPU 快取作業，因為沒有任何參與者實際使用 CPU 進行讀取/寫入。

新增時間：19 歲

名稱	值	說明
CPU	`0`
RAM	`1`
無法存取	`2`

錯誤彈性

類型：uint32

定義於 fuchsia.sysmem2/error.fidl

無論哪個錯誤代碼，任何用戶端重試次數都應非常有限 (如果有的話)。

由於 zx_status_t 中的正值已淘汰，因此錯誤值不應儲存在 zx_status_t 中。

新增時間：19 歲

名稱	值	說明
INVALID	`0`	在這個錯誤列舉中，這不是有效的錯誤值。伺服器絕不會將這個值做為失敗代碼傳送。系統不會將這個值視為「成功」。在某些語言中，本機初始化的 Error 執行個體具有此值，直到使用有效的正向錯誤代碼初始化為止。
未指定	`1`	不明錯誤。如果未套用其他錯誤代碼，系統就會顯示這個錯誤代碼，且該錯誤可能並非因為透過傳送這個錯誤的管道傳送至伺服器的問題訊息。用戶端應將這個錯誤視為一般錯誤處理。例如，當其他用戶端管道意外從用戶端意外關閉 (沒有先傳送 fuchsia.sysmem2/Node.Release) 時，就會產生這個錯誤，導致同一樹狀結構或子樹狀結構中的任何節點發生錯誤。在這個使用情況中，最重要的是不是接收用戶端的「錯誤」，因為接收的用戶端可能完全無法處理錯誤，所以沒有原因更具體。再舉一個例子，如果系統預期將失敗的系統呼叫意外失敗，並且沒有找出原因導致用戶端「毀損」時，就可以使用這個錯誤。用戶端不應要求 / 依賴導致 UNSPECIFIED 的特定錯誤原因，因為任何特定錯誤原因都可能導致未來開始產生更具體的錯誤代碼。
PROTOCOL_DEVIATION	`2`	未設定必填欄位，或指定的值無效。詳情請參閱記錄檔。如果從用戶端收到訊息的順序錯誤或與通訊協定規則不一致，也會使用。
NOT_FOUND	`3`	找不到客戶指定的物件或 ID。
HANDLE_ACCESS_DENIED	`4`	物件帳號代碼權限不足，無法執行要求。
NO_MEMORY	`5`	缺乏可用記憶體，因此無法滿足配置。記憶體耗盡可能僅適用於限制匯總期間選取的堆積。因此，即使一般系統 RAM 未接近耗盡，還是可能會發生這項錯誤，具體情況取決於設定和選取的堆積而定。
CONSTRAINTS_INTERSECTION_EMPTY	`6`	要求有效，但因硬體限製而無法滿足。如果參與這個配置的參與者有不相容的限制 (無異的交集)，就會發生這種情形。詳情請參閱記錄。若系統可能會將參與者視為非必要，請參閱 BufferCollectionTokenGroup。如果現有集合中的緩衝區不足以滿足透過 fuchsia.sysmem2/BufferCollection.AttachToken 建立的額外符記 (包括衍生權杖的子樹狀結構)，也可能會發生這種情況。如果用戶端的節點屬於某個群組，而改為選取其他群組子項，也可能會發生這種情況。
待處理	`7`	尚未嘗試分配。呼叫 fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated 會封鎖。
TOO_MANY_GROUP_CHILD_COMBINATIONS	`8`	目前考慮過太多 `BufferCollectionTokenGroup` 子項權杖選取組合，因此造成 sysmem 無法分配分配，而不是列舉其餘的組合。

資料表

AllocatorAllocateNonSharedCollectionRequest 資源

序數	欄位	類型	說明
1	`collection_request`	`server_end<BufferCollection>`

AllocatorAllocateSharedCollectionRequest 資源

序數	欄位	類型	說明
1	`token_request`	`server_end<BufferCollectionToken>`

AllocatorBindSharedCollectionRequest 資源

序數	欄位	類型	說明
1	`token`	`BufferCollectionToken`
2	`buffer_collection_request`	`server_end<BufferCollection>`

AllocatorGetVmoInfoRequest 資源

序數	欄位	類型	說明
1	`vmo`	`handle<vmo>`	必須設定 `vmo`；擁有權會轉移至伺服器，因此在大多數情況下，用戶端會複製一個控制代碼，並透過這個欄位轉移重複項目。

AllocatorSetDebugClientInfoRequest

序數	欄位	類型	說明
1	`name`	`string[256]`
2	`id`	`uint64`

AllocatorValidateBufferCollectionTokenRequest

序數	欄位	類型	說明
1	`token_server_koid`	`zx/Koid`

Allocator_GetVmoInfo_Response 資源

序數	欄位	類型
1	`buffer_collection_id`	`uint64`
2	`buffer_index`	`uint64`
3	`close_weak_asap`	`handle<eventpair>`

Allocator_ValidateBufferCollectionToken_Response

序數	欄位	類型	說明
1	`is_known`	`bool`

BufferCollectionAttachLifetimeTrackingRequest 資源

序數	欄位	類型	說明
1	`server_end`	`handle<eventpair>`
2	`buffers_remaining`	`uint32`

BufferCollectionAttachTokenRequest 資源

序數	欄位	類型	說明
1	`rights_attenuation_mask`	`zx/Rights`
2	`token_request`	`server_end<BufferCollectionToken>`

BufferCollectionConstraints

分配的緩衝區有的限制，以及 (選用) 儲存在緩衝區中的圖片限制。您可以為每位參與者指定這些限制。sysmem 服務會實作多個參與者的限制匯總。

新增時間：19 歲

序數	欄位	類型	說明
1	`usage`	`BufferUsage`	`usage` 是提示 sysmem 的提示，如有多個相容的選項，可能有助於選擇更理想的 fuchsia.images2/PixelFormat 和/或 `pixel_format_modifier`。匯總 fuchsia.sysmem2/BufferCollectionConstraints 時，這些值採用位元-OR。必須指定至少一個 `usage` 位元 (但是，fuchsia.sysmem2/BufferCollection.SetConstraints 要求沒有設定要求 `constraints` 欄位，在此情況下，`kNoneUsage` 為預設值，且參與者沒有限制)。如果指定 `kNoneUsage`，則必須是唯一已設定的位元，而且不會為了回應 fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated 而傳送 VMO。
2	`min_buffer_count_for_camping`	`uint32`	每位參與者可以同時保留給專屬使用的緩衝區數量，且持續時間超過一段短暫的時間 (露營)。在這種情況下，「暫時」持續時間是指完成少量非阻塞程式碼，進而完成緩衝區的擁有權轉移程序所花費的時間。從儲存空間讀取資料、等待尚未執行的硬體，或是進行影格編碼或解碼這類操作等作業，均不視為暫時持續時間，即使有時很快完成也一樣。舉例來說，影片解碼器會指定 (至少) 參照影格數量上限 + 1 個影格目前已解碼。但是，對於會執行非同步並快速提供先前解碼影格的程式碼，請不要再使用 1 個，即便該影格可能擁有時間與下一個影格的解碼作業同時進行也一樣。參與者露營的緩衝區數量不得超出此處指定的數量 (暫時性的緩衝時間除外)，否則處理程序可能會卡住。匯總 BufferCollectionConstraint 時，系統會加入這些值。在測試情境中，如果露營的緩衝區數量大於這個值，則如果持續時間夠長 (在此情境中，一個畫面重新整理週期就「顯著」)，系統可能會將其標記為失敗。在測試情境中，系統可能無法為參與者提供的緩衝區數量超過並行的緩衝區數量。
3	`min_buffer_count_for_dedicated_slack`	`uint32`	每個參與者為簡化原因而需要的緩衝區數量下限，藉此改善處理重疊情形 / 提升效能。匯總 `BufferCollectionConstraints` 時，這些值會相加。參與者通常應在此指定 0 或 1。如果 `min_buffer_count_for_camping` 已足以讓參與者忙碌的時間在參與者稍晚的 100% 時間內保持忙碌，那麼通常為 0；如果以壓縮活動原因為 100% 的時間額外提供足夠的緩衝，而不需額外耗費 100 % 的時間，則 1 則適合。在測試情境中，這個欄位可能強制設為 0，所以所有參與者應該都能繼續運作，不會卡住。如果前進的進度需要緩衝區，則該緩衝區應在 `min_buffer_count_for_camping` 中納入考量。
4	`min_buffer_count_for_shared_slack`	`uint32`	與 `min_buffer_count_for_dedicated_slack` 類似，但匯總這些值的最大值 (而非新增值) 除外。這裡的值不會與任何參與者的 `min_buffer_count_for_dedicated_slack` 分享。如果參與者想確保整體來說有一部分，但不需要專屬的堆疊，可以在此處指定 > 0。要選擇使用 `min_buffer_count_for_dedicated_slack` 或 `min_buffer_count_for_shared_slack` (或同時使用兩者)，通常與額外堆疊改善效能的程度有關。在測試情境中，這個欄位可能強制設為 0，所以所有參與者應該都能繼續運作，不會卡住。如果前進的進度需要緩衝區，則該緩衝區應在 `min_buffer_count_for_camping` 中納入考量。
5	`min_buffer_count`	`uint32`	幸福的參與者可能不需要要求 `buffer_count` 的範圍，甚至是特定的 `buffer_count`。除非參與者確實必須設定這個欄位來限制整體 `BufferCollectionInfo.buffer_count`，否則這個欄位應保持 0。這類參與者仍應視情況填寫 min_buffer_count_for_* 欄位。如未設定這個欄位，邏輯 `min_buffer_count` 則為 0。
6	`max_buffer_count`	`uint32`	幸福的參與者可能不需要要求 `buffer_count` 的範圍，甚至是特定的 `buffer_count`。除非參與者確實必須設定這個欄位來限制整體 `BufferCollectionInfo.buffer_count`，否則這個欄位應保持 0。該參與者仍應填寫 min_buffer_count_for_* 欄位。如果未設定這個欄位，邏輯 `max_buffer_count` 會是 0xFFFFFFFF。
7	`buffer_memory_constraints`	`BufferMemoryConstraints`	`BufferCollectionSettings.buffer_settings` 的選用限制。打算設定 `image_format_constraints` 的參與者通常會透過 `image_format_constraints` 隱含指定緩衝區的下限，而且可能只能透過 `buffer_memory_constraints` 僅指定緩衝區大小上限。如果未設定，用戶端會指定「不在乎」，系統會重新指定任何緩衝區記憶體限制。
8	`image_format_constraints`	`vector<ImageFormatConstraints>[64]`	針對儲存在集合緩衝區中的圖片，其圖片格式參數的選用限制。包括 fuchsia.images2/PixelFormat 和 `pixel_format_modifier` (用於傾斜等動作)。這些限制條件可以依照 `pixel_format` `pixel_format_modifier` 組合個別指定。`pixel_format` 組 `pixel_format_modifier` 組不得重複。匯總時，只會保留`pixel_format` `pixel_format_modifier`組合，且這些對象必須指定並非零的參與者 `image_format_constraints`大小 (非空值) BufferCollectionConstraints。參與者可以指定 `pixel_format` fuchsia.images2/PixelFormat.DO_NOT_CARE 和/或 `pixel_format_modifier` fuchsia.images2/FORMAT_MODIFIER_DO_NOT_CARE 以允許選取任何值，但至少要有一位參與者指定特定格式，才能整體分配。在 SetConstraints 訊息中，未設定長度或長度為零，代表沒有圖片格式限制；如果沒有其他參與者指定任何 `image_format_constraints` 項目，則系統可以分配原始緩衝區。

BufferCollectionInfo 資源

緩衝區收集及其緩衝區的相關資訊。

新增時間：19 歲

序數欄位類型說明

1

settings

SingleBufferSettings

這些設定會套用至初始緩衝區分配中的所有緩衝區。

系統一律會由 sysmem 設定這個欄位。

2

buffers

vector<VmoBuffer>[128]

VMO 會為集合中的每個緩衝區處理 (和 vmo_usable_start offset)。

這個向量的大小為 buffer_count (buffer_count 不會分開傳送)。

所有緩衝區 VMO 控制代碼的大小和存取權相同。大小則位於 settings.buffer_settings.size_bytes。

VMO 存取權取決於用戶端在分配緩衝區集合時指定的用量。例如，表示唯讀用法的用戶端會收到沒有寫入權利的 VMO。此外，權利可透過對 BufferCollectionToken.Duplicate() 呼叫的參數引用。

即使參與者指定使用情況，但不需要使用 VMO 處理，這個欄位仍會一律包含 VmoBuffer。這樣一來，這類參與者就能知道 vmo_usable_start 值，以防參與者有任何使用的情況。

即使參與者未指定任何緩衝區用途，系統一律會設定這個欄位，但在這種情況下，系統不會設定這個欄位中的 fuchsia.sysmem2/VmoBuffer.vmo 子欄位。

3

buffer_collection_id

uint64

每次開機時，所有邏輯緩衝區集合中的這個數字都不會重複。

與相同邏輯緩衝區集合相關聯的所有 BufferCollectionToken(s)、BufferCollection(s) 和 BufferCollectionTokenGroup(衍生自透過 fuchsia.sysmem2.Allocator.CreateSharedCollection 或與 CreateNonSharedCollection) 相關聯的 BufferCollectionTokenGroup (s) 都相同。

可使用 GetBufferCollectionId 從 BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup 擷取相同的 ID (需在往返 sysmem 和返回之間)。

系統一律會由 sysmem 設定這個欄位。

BufferCollectionSetConstraintsRequest 資源

序數	欄位	類型	說明
1	`constraints`	`BufferCollectionConstraints`

BufferCollectionTokenCreateBufferCollectionTokenGroupRequest 資源

序數	欄位	類型	說明
1	`group_request`	`server_end<BufferCollectionTokenGroup>`

BufferCollectionTokenDuplicateRequest 資源

序數	欄位	類型	說明
1	`rights_attenuation_mask`	`zx/Rights`
2	`token_request`	`server_end<BufferCollectionToken>`

BufferCollectionTokenDuplicateSyncRequest

序數	欄位	類型	說明
1	`rights_attenuation_masks`	`vector<zx/Rights>[64]`

BufferCollectionTokenGroupCreateChildRequest 資源

序數	欄位	類型	說明
1	`token_request`	`server_end<BufferCollectionToken>`	必須設定。
2	`rights_attenuation_mask`	`zx/Rights`	如果未設定，則預設值為 `ZX_RIGHT_SAME_RIGHTS`。

BufferCollectionTokenGroupCreateChildrenSyncRequest

序數	欄位	類型	說明
1	`rights_attenuation_masks`	`vector<zx/Rights>[64]`

BufferCollectionTokenGroup_CreateChildrenSync_Response 資源

序數	欄位	類型	說明
1	`tokens`	`vector<BufferCollectionToken>[64]`

BufferCollectionToken_DuplicateSync_Response 資源

序數	欄位	類型	說明
1	`tokens`	`vector<BufferCollectionToken>[64]`

BufferCollection_WaitForAllBuffersAllocations_Response 資源

序數	欄位	類型	說明
1	`buffer_collection_info`	`BufferCollectionInfo`

BufferMemoryConstraints

新增時間：19 歲

序數	欄位	類型	說明
1	`min_size_bytes`	`uint64`	系統會將未設定的值視為 1
2	`max_size_bytes`	`uint64`	系統會將未設定的值視為 0xFFFFFFFFFFFFFF。
3	`physically_contiguous_required`	`bool`	設為 false 時，緩衝區 VMO 的實體頁面可能不具連續性。如為 true，緩衝區 VMO 的實體頁面必須依序排列。不需要實體連續 VMO 的用戶端仍須接受實體連續的 VMO 或「實體」VMO。
4	`secure_required`	`bool`	如果為 true，參與者需要安全記憶體。匯總 `BufferCollectionConstraints` 時，這些值為布林值，或。
5	`cpu_domain_supported`	`bool`	如果為 true (或 `BufferMemoryConstraints` 不存在時)，參與者仍可透過 sysmem 選取 CPU 網域。如果選取 CPU 網域，參與者必須確保 CPU 可以在緩衝區中讀取或寫入資料，而且參與者之外沒有快取作業。
6	`ram_domain_supported`	`bool`	如果為 true，參與者可以選擇讓 sysmem 選取 RAM 網域。如果選取 RAM 網域，RAM 內就必須有生產端資料 (CPU 快取狀態，使 RAM 資料不會因骯髒 CPU 快取行寫入 RAM 的毀損)，且使用 CPU 讀取的取用端必須將 CPU 快取失效，然後再讀取 (生產端不保證「乾淨」快取行沒有過時)
7	`inaccessible_domain_supported`	`bool`	若為 true，參與者可以選擇允許 sysmem 選取 INACCESSIBLE 網域。如果選取 INACCESSIBLE 網域，則 CPU 無法讀取和寫入資料。如果嘗試使用 CPU 讀取/寫入資料，可能會導致 UB 和/或程序終止。如果選取 INACCESSIBLE 網域，參與者只能使用 HW 執行的指定行銷區域，或類似平台專屬指定行銷區域 (DMA) 對安全環境的要求，對資料執行作業。安全堆積僅支援 INACCESSIBLE 網域，如果其他 `BufferUsage` 參與者並未將 inaccess_domain_supported 設為 true，安全堆積就會失敗。`NONE_USAGE`
8	`permitted_heaps`	`vector<Heap>[64]`	參與者可以接受的堆積。如果參與者未擔心分配到哪些堆積記憶體，就應該將這個欄位設為未設定。只有在所有參與者明確指出可透過 `heap_permitted` 使用安全堆積，或指定 `NONE_USAGE` 時，系統才會選取安全堆積。

BufferMemorySettings

這些是緩衝區集合所有緩衝區的記憶體相關設定。

新增時間：19 歲

序數	欄位	類型	說明
1	`size_bytes`	`uint64`	系統一律會由 sysmem 設定這個欄位。
2	`is_physically_contiguous`	`bool`	系統一律會由 sysmem 設定這個欄位。
3	`is_secure`	`bool`	系統一律會由 sysmem 設定這個欄位。
4	`coherency_domain`	`CoherencyDomain`	系統一律會由 sysmem 設定這個欄位。
5	`heap`	`Heap`	緩衝區分配的特定堆積。系統一律會由 sysmem 設定這個欄位。

BufferUsage

定義於 fuchsia.sysmem2/usages.fidl

說明用戶端如何存取緩衝區的內容。

新增時間：19 歲

序數	欄位	類型	說明
1	`none`	`uint32`	如果用戶端設定了這個欄位，用戶端就不應在同一個資料表執行個體中設定任何其他欄位。這個欄位中唯一的有效位元是 `NONE_USAGE`，如果已設定這個欄位，就必須設定這個值。這個欄位及這個欄位中設定的部分，基本上是證明用戶端確實不會使用緩衝區，因此不需要任何 VMO (光是填寫表格也無妨)。
2	`cpu`	`uint32`	如已設定，會保留 CPU 用量位元。請參閱 usages.fidl 中的 `CPU_USAGE_*` 旗標。
3	`vulkan`	`uint32`	設定後，保留 vulkan 使用位元。請參閱 usages.fidl 中的 `VULKAN_IMAGE_` 和 `VULKAN_BUFFER_` 位元。`VULKAN_USAGE_*` 位元定義/名稱已淘汰，
4	`display`	`uint32`	設定後會保留顯示用量位元。請參閱 usages.fidl 中的 `DISPLAY_USAGE_*` 位元。
5	`video`	`uint32`	設定後，保存影片用量資料。請參閱 usages.fidl 中的 `VIDEO_USAGE_*` 位元。

堆積

堆積執行個體的參照。

特定堆積執行個體可以有多個 Heap，可用於參照堆積執行個體。在不知道這些 Heap 別名的情況下比較 Heap 資料表並非可靠的方法，因此無法確定兩個 Heap 資料表是否參照相同的堆積 (比對結果為「是」，但不相符可能代表可能)。如果允許堆積別名，重新命名 Heap.type 就會更輕鬆。

新增時間：19 歲

序數欄位類型說明

1

heap_type

string[128]

堆積的類型，利用結構定義定義的繫結字串，以及 fuchsia.sysmem.heap.bind 檔案中註解中描述的機制來指定。

例如：

"fuchsia.sysmem.heap.HEAP_TYPE.SYSTEM_RAM"
"fuchsia.goldfish.platform.sysmem.heap.HEAP_TYPE.HOST_VISIBLE"

2

id

uint64

堆積的 uint64 ID。只有每個 (類型、啟動) 元組的不重複值。換句話說，指定的堆積 ID 僅在機器目前的啟動階段 (而非啟動之間) 才有意義，且僅限於 Heap.type 內。

對於參照單例堆積的 Heap.type，如果參與者在 fuchsia.sysmem2.BufferMemoryConstraints.permitted_heaps 中指定單例堆積，可以將這個欄位未設定或設為零。Sysmem 一律會為 fuchsia.sysmem2.BufferMemmorySettings.heap 中指定的堆積填寫此欄位 (如果是單例模式堆積，id 欄位會由 sysmem 設為 0)。

ImageFormatConstraints

說明緩衝區中圖片資料版面配置的限制。

序數	欄位	類型	說明
1	`pixel_format`	`fuchsia.images2/PixelFormat`	適用以下限制的 fuchsia.images2/PixelFormat。伺服器會將 `pixel_format` 和 `pixel_format_modifier` 欄位視為一個額外的 `pixel_format_and_modifiers` 項目。參與者可能有多個 fuchsia.sysmem2/PixelFormatAndModifier。如果不同 `PixelFormatAndModifier` 的圖片限制相同，參與者可能會在 `pixel_format_and_modifiers` 欄位中列出其他 `PixelFormatAndModifier`，套用限制條件。這樣可以減少需要傳送的 `ImageFormatConstraints` 總數，而且不會變更意義 (例如，傳送許多僅因 `pixel_format` 和 `pixel_format_modifier` 不同，且整體指定相同的 `PixelFormatAndModifier` 清單) 的多個獨立 `ImageFormatConstraints`。如果不同 `PixelFormatAndModifier` 的圖片限制不同，參與者就能針對具有不同圖片限制的每組 `PixelFormatAndModifier` 在 `image_format_constraints` 中，透過個別的 `ImageFormatConstraints` 項目傳達這一點。您可以在參與者擁有兩個 `image_format_constraints` 項目的情況下，因為其 pixel_format_and_modifiers 是只有不同的，但這並不是最精簡的方式，因為在單一 `ImageFormatConstraints` 中指定兩個 `PixelFormatAndModifier` 就可以合併這兩個項目。 `ImageFormatConstraints` 的其他欄位通常會因 `pixel_format` 或 `pixel_format_modifier` 而異，例如線性格式可支援小於定格格式的線性格式。另請參閱 fuchsia.sysmem2/ImageFormatConstraints.pixel_format_and_modifiers。除非 `pixel_format_and_modifiers` 不是空白，否則 Thie 欄位必須設為 fuchsia.images2/PixelFormat.INVALID 以外的值。換句話說，每個 `ImageFormatConstraints` 至少要有一個 `PixelFormatAndModifier`。如果設定了 `pixel_format_modifier`，就必須設定這個欄位。如果參與者需要指定 `ImageFormatConstraints`，且不限制 `pixel_format`，參與者可以指定 fuchsia.images2/PixelFormat.DO_NOT_CARE。
2	`pixel_format_modifier`	`fuchsia.images2/PixelFormatModifier`	要套用以下限制條件的像素格式修飾符。伺服器會將 `pixel_format` 和 `pixel_format_modifier` 欄位視為一個額外的 `pixel_format_and_modifiers` 項目。這個值來自 `fuchsia.images2` format_modifier.fidl 與 `pixel_format` 搭配使用，參與者可以接受。另請參閱 `pixel_format_and_modifiers`。如果已設定 `pixel_format`，但未設定 `pixel_format_modifier`，則預設值取決於其他欄位：如果 `pixel_format` 為 `DO_NOT_CARE`，像素格式修飾符就是 `FORMAT_MODIFIER_DO_NOT_CARE`。否則，如果 `BufferCollectionConstraints.usage` 不是 `NONE`，像素格式修飾符就是 `FORMAT_MODIFIER_LINEAR`。否則像素格式修飾符就是 `FORMAT_MODIFIER_DO_NOT_CARE`。設定後，這個值會是特定修飾符 (不只是旗標) 或 `FORMAT_MODIFIER_DO_NOT_CARE`，而且這個值來自 `fuchsia.images2` format_modifier.fidl 中定義的一組值。
3	`color_spaces`	`vector<fuchsia.images2/ColorSpace>[32]`	空白是錯誤。重複項目均發生錯誤。任意順序並非錯誤。用戶端可以指定單一項目 [fuchsia.sysmem2/ColorSpace.DO_NOT_CARE`] if the client doesn't want to constrain which` ColorSpace`is chosen. At least one participant must specify at least one`ColorSpace`value other than`ColorSpace.DO_NOT_CARE`)，否則分配作業會失敗。
4	`min_size`	`fuchsia.math/SizeU`	可接受的最小尺寸 (以像素為單位)。舉例來說，影片解碼器參與者可將這個欄位設為串流可能指定的最小尺寸。相反地，`required_min_size` 會設為串流指定的目前大小。`min_size` 會取用最大值來匯總，`required_min_size` 則會利用最小值來匯總。傳送至 sysmem 時，如果參與者已準備好處理最小的非零圖片版面配置，但僅限於由 `pixel_format` 和 `pixel_format_modifier` 隱含的限制限制，就無法設定這個欄位。這個欄位也可以設為參與者可處理的實際最小尺寸。製作者應設定 `min_size`，並將寬度和高度設定為生產端可能產生的實際最小寬度和高度，而非零。舉例來說，影片解碼器可以在這裡設定單一巨集區塊的大小。從 sysmem 接收資料時，系統會一律設定這個欄位，寬度和高度都不是 0，因為至少一位參與者必須指定非零的最小尺寸 (寬度和高度都不是零)。另請參閱 `required_min_size`。
5	`max_size`	`fuchsia.math/SizeU`	大小上限 (以像素為單位)。舉例來說，View 可能會將這個欄位 (直接或透過子參與者) 設為可合併的大小上限。傳送至 sysmem 時，系統會將未設定大小視為 0xFFFFFFFF、0xFFFFFFFF。從 sysmem 接收時，系統一律會設定這個欄位。針對個別的寬度和高度，如果沒有強制執行上限，該子欄位會是 0xFFFFFFFF。另請參閱 `required_max_size`。
6	`min_bytes_per_row`	`uint32`	每個資料列的位元組數下限，包括一列中最後圖片資料以外的任何邊框間距。這有時稱為「跨位元組」或「行距偏移」。如果是單一平面格式，這是指每列的像素數量 (以位元組為單位)。如為多平面格式，這是指平面 0 中每個資料列的樣本位元組數 (例如在多平面 YUV 格式的情況下，每個資料列的 luma 樣本位元組數)。如果是多平面格式，飛機 0 以外每列的位元組則視格式而定，但一律是與每列 0 個位元組的特定關係。將 `ImageFormatConstraints` 傳送至 sysmem 時，您可以選擇是否要設定這個欄位。除非參與者需要強制 `bytes_per_row` 大於 `min_size.width` 隱含的最小值、`pixel_format` 的「跨寬度像素」加上 `pixel_format_modifier` (另請參閱 `ImageFormatStrideBytesPerWidthPixel`) 和 `bytes_per_row_divisor`，否則我們不建議設定這個欄位。收到 sysmem 的這個結構時，系統一律會設定此欄位 (如果有父項結構)，並且一律至少設定 `min_size.width` 所隱含的值、`pixel_format` 加上 `pixel_format_modifier` 的「跨寬度位元組數」以及 `bytes_per_row_divisor`。部分生產端參與者可能只想將 `ImageFormat.bytes_per_row` 設為 `ImageFormatConstraints.min_bytes_per_row`，因為 sysmem 可確保 `min_bytes_per_row` 與寬度 `min_size.width` 的圖片相容。不過，需要 `size.width` > `min_size.width` 的生產端參與者可以從 `ImageFormatMinimumRowBytes` (在 C++ 中) 取得對應 `min_bytes_per_row`，也可以直接計算 `bytes_per_row`。
7	`max_bytes_per_row`	`uint32`	每個資料列的位元組數上限，包括資料列中最後一張圖片資料以外的任何邊框間距。傳送至 sysmem 時，必須 >= `max_size.width` 隱含的值、「每個寬度像素的跨位元組」和 `bytes_per_row_divisor`，否則限制匯總將會失敗。如未設定，則表示參與者不需要/希望設定嚴格的上限。傳送至 sysmem 時，系統會將未設定大小視為 0xFFFFFFFF。從 sysmem 收到時，系統一律會設定這個欄位。如果上限實際上是無限大，這個值會是 0xFFFFFFFF (而非 0)。
8	`max_width_times_height`	`uint64`	像素的數量上限。像素上限 (以像素為單位) 會透過 fuchsia.sysmem/BufferMemoryConstraints.max_size_bytes 與產生的 fuchsia.sysmem/BufferSettings.size_bytes 間接限制，且您也可直接透過這個欄位強制執行。相較於會個別限制寬度和高度的 fuchsia.sysmem2/ImageFormatConstraints.max_size 欄位，這個欄位會限制像素總數。與 fuchsia.sysmem/BufferMemoryConstraints.max_size_bytes 相比，這個欄位並未限制每列像素後方的非像素邊框間距位元組數量。如果是圖塊 `pixel_format_modifier`，這個欄位也不會限制非像素位元組的數量。與一般長寬比相比，非常窄或非常短的圖片顯示比例可能會導致每個像素的效能降低。極端長寬比通常會增加邊框間距和/或記憶體頻寬負擔。參與者可使用 [fuchsia.sysmem/ImageFormatConstraints.min_size`] 表示不支援極窄或非常窄的維度。傳送至 sysmem 時，系統會將未設定大小視為 0xFFFFFFFF。從 sysmem 接收時，系統一律會設定此欄位，可設為 0xFFFFFFFF。
9	`size_alignment`	`fuchsia.math/SizeU`	圖片 `size` 的對齊要求。 `size.width % size_alignment.width` 必須是 0。 `size.height % size_alignment.height` 必須是 0。如未設定，系統會視為 1、1。
10	`display_rect_alignment`	`fuchsia.math/SizeU`	`display_rect` 的對齊要求。 `display_rect.x % display_rect_alignment.width` 必須是 0。 `display_rect.y % display_rect_alignment.height` 必須是 0。 `display_rect.width % display_rect_alignment.width` 必須是 0。 `display_rect.height % display_rect_alignment.height` 必須是 0。如未設定，系統會視為 1、1。
11	`required_min_size`	`fuchsia.math/SizeU`	這些欄位可用於確保匯總限制條件具有 `min_size` 和 `max_size`，以便 `required_min_size` 和 `required_max_size` (以及符合校正要求之間的任何項目) 皆為 `ImageFormat.size` 的允許值。舉例來說，生產端影片解碼器不想限制允許的 `ImageFormat.size`，因為壓縮串流可能會變更串流中的尺寸，但生產端影片解碼器必須確保匯總限制在串流中目前位置至少允許目前大小的未壓縮影格。再舉一個例子，打算解碼影片的啟動器可能知道串流中影格的預期大小上限，因此，只要設定 `required_max_size`，即可確保分配的緩衝區大小足以支援該上限 `size`。除了成功分配之外，發起人也會知道消費者參與者可接受 `size` 的上限。生產端或發起人設定這些欄位，通常會比取用端設定這些欄位更為常見。雖然 `min_size` 和 `max_size` 是透過有效利用交集來匯總，而 `required_min_size` 和 `required_max_size` 則會有效彙整聯集來匯總。這個欄位會取得每個元件的最小值，而 required_max_size 匯總是取得每個元件的最大值。如未設定，系統會視為 0xFFFFFFFF、0xFFFFFFFF。
12	`required_max_size`	`fuchsia.math/SizeU`	另請參閱 `required_min_size`。如未設定，系統會視為 0, 0。
13	`bytes_per_row_divisor`	`uint32`	`fuchsia_images2.ImageFormat.bytes_per_row % bytes_per_row_divisor` 必須是 0。系統會將未設定的值視為 1。如果意圖是為了確保「bytes_per_row」是位元組大小的倍數，建議您使用 `require_bytes_per_row_at_pixel_boundary`。如果意圖是確保寬度 (以像素為單位) 對齊，則建議使用 `size_alignment.width`。相反地，這個欄位可以指定「跨位元組」(從圖片開頭到列開頭的位元組偏移到第 n-1 列開頭的位元組偏移，到第 n-1 列開頭的位元組偏移，結果為位元組) 必須對齊指定的位元組數。例如，在使用 `PixelFormat.BGR24` (24 位元顏色；每像素 3 位元組) 時，參與者通常需要從圖片開頭的 4 個位元組開始對齊，這可能代表每列結尾的像素結尾處，在像素的下一列開頭之前會有邊框間距。雖然您可以透過將 `size_alignment.width` 設為「每個寬度像素的順位」最小的倍數來強制執行 `bytes_per_row_divisor` 的任何值，但強制採用跨距對齊要求，以執行不必要的邊框間距 (意即可能比所需還要大的緩衝區更多)，而且這可能導致「假的」`size.width`，以避免這種狀況。而是直接在這裡指定以位元組為單位的跨距對齊要求。
14	`start_offset_divisor`	`uint32`	`vmo_usable_start % start_offset_divisor` 必須是 0。如未設定，系統會將此視為 1。除非實際需要，否則我們不建議生產端參與者設定非零圖片起始偏移 (來自緩衝區基礎)，因為並非所有參與者都能正確處理非零的圖片起始偏移。
15	`pixel_format_and_modifiers`	`vector<PixelFormatAndModifier>[64]`	適用下列限制條件的 (額外) fuchsia.sysmem2/PixelFormatAndModifier。舉例來說，如果參與者只想為這個 fuchsia.sysmem2/ImageFormatConstraints 設定單一 `PixelFormatAndModifier`，則參與者可以 (a) 使用 `pixel_format` 和 `pixel_format_modifier` 欄位來指定一個 `PixelFormatAndModifier` 的欄位，但不要設定 `pixel_format_and_modifiers`，或者 (b) 不設定 `pixel_format` 和 `pixel_format_modifier` 欄位，並將一個 `PixelFormatAndModifier` 欄位留空。`pixel_format_and_modifiers` 如果設定了 `pixel_format`，伺服器就會採用 pixel_format 和 pixel_format_modifier 欄位 (在過程中取消設定)，然後將這兩個欄位封裝到 `PixelFormatAndModifier` 中，再將其移至這個向量上另一個項目，整體大小限制為 `MAX_COUNT_PIXEL_FORMAT_AND_MODIFIERS + 1`。伺服器將 `pixel_format`、`pixel_format_modifier` 移入這個向量中的另一個項目後，此向量不得空白。如果產生的清單含有超過 1 個項目，這個向量中的項目就等同於清單 (大小) 的獨立 `ImageFormatConstraints` 項目 (簡寫)，每個 `pixel_format_and_modifiers` 項目各有一個 `PixelFormatAndModifier`，其中所有獨立的 `ImageFormatConstraints` 項目都有相同的限制 (依欄位比較，不包括 `pixel_format`、`pixel_format_modifier` 或 `pixel_format_and_modifiers` 欄位)。在 `SetConstraints` 訊息中，每個項目會指定參與者可接受的 `PixelFormatAndModifier` (假設也滿足下列限制條件欄位)。在對 `WaitForAllBuffersAllocated` 的回應中，系統會取消設定這個欄位，並使用 `pixel_format` 和 `pixel_format_modifier` 欄位表示所選 `PixelFormatAndModifier`。在來自參與者的 `SetConstraints` 訊息中，所有 `PixelFormatAndModifiers` 的項目均不得重複。`image_format_constraints`如果項目中使用 `fuchsia.images2.PixelFormat.DO_NOT_CARE`，則沒有任何其他項目 (考量 `image_format_constraints` 底下的所有項目) 與 `pixel_format_modifier` 相符。如果使用 `FORMAT_MODIFIER_DO_NOT_CARE`，就無法與 `pixel_format` 相符的任何其他項目 (考量 `image_format_constraints` 下的所有項目)。在本例中，包含 `DO_NOT_CARE` 或 `FORMAT_MODIFIER_DO_NOT_CARE` (但非兩者) 的 `PixelFormatAndModifier` 值可與另一個參與者的 `PixelFormatAndModifier` 結合，與其他表示「不關心」的欄位合併，進而產生可成功分配的完整的 `PixelFormatAndModifier`。不過至少目前，一個參與者不得在不同欄位中指定兩個分別具有「不關心」的 `PixelFormatAndModifier` 值。這項操作不會禁止同時含有 DO_NOT_CARE 和 PIXEL_FORMAT_DO_NOT_CARE (只是單一 `PixelFormatAndModifier` 值) 的單一 `PixelFormatAndModifier`。如果用戶端確實需要使用 `pixel_format_modifier` FORMAT_MODIFIER_DO_NOT_CARE，以及與 `pixel_format` DO_NOT_CARE 相關的 `pixel_format_modifier` 相關限制，指定與 `pixel_format` 相關的某些限制，則用戶端可複製權杖，並使用/導出兩個單獨的參與者。如要進一步瞭解與單一 `ImageFormatConstraints` 中多個 `PixelFormatAndModifier` 相關的其他留言，請參閱 `pixel_format`。
16	`require_bytes_per_row_at_pixel_boundary`	`bool`	如果設定和 True，則產生的 ImageFormatConstraints 中的位元組_per_row_divisor 為一個值，該值需要 bytes_per_row 代表像素的整數。這可能會導致每個資料列結尾的邊框間距，與這個欄位未設為 True 的情況更多，但可確保能以像素整數表示。舉例來說，如果所選的 `PixelFormat` 為 `B8G8R8`，如果這個欄位設為 true，則產生的位元組_per_row_divisor 會是 3 的倍數。在此範例中，如果其他參與者將 `bytes_per_row_divisor` 設為 4，則產生的 `bytes_per_row_divisor` 會是 12 的倍數。

NodeIsAlternativeForRequest 資源

序數	欄位	類型	說明
1	`node_ref`	`handle<event>`

NodeSetDebugClientInfoRequest

序數	欄位	類型	說明
1	`name`	`string[256]`
2	`id`	`uint64`

NodeSetDebugTimeoutLogDeadlineRequest

序數	欄位	類型	說明
1	`deadline`	`zx/Time`

NodeSetNameRequest

序數	欄位	類型	說明
1	`priority`	`uint32`
2	`name`	`string[64]`

NodeSetWeakOkRequest 資源

序數	欄位	類型	說明
1	`for_child_nodes_also`	`bool`

Node_GetBufferCollectionId_Response

序數	欄位	類型	說明
1	`buffer_collection_id`	`uint64`

Node_GetNodeRef_Response 資源

序數	欄位	類型	說明
1	`node_ref`	`handle<event>`

Node_IsAlternateFor_Response

序數	欄位	類型	說明
1	`is_alternate`	`bool`

SingleBufferSettings

這些設定和限制會套用至集合中的所有緩衝區。

新增時間：19 歲

序數欄位類型說明

1

buffer_settings

BufferMemorySettings

系統一律會由 sysmem 設定這個欄位。

2

image_format_constraints

ImageFormatConstraints

如果緩衝區含有非未壓縮圖片資料的資料，就不會有這個欄位設定。如果緩衝區含有未壓縮圖片資料的資料，則「可能」具有這個欄位設定。

至少目前，變更 PixelFormat 就必須重新分配緩衝區。

如未設定，就不會有圖片格式限制。

VmoBuffer 資源

新增時間：19 歲

序數欄位類型說明

1

vmo

handle<vmo>

如果參與者僅將 fuchsia.sysmem2/BufferUsage.none 設為 NONE_USAGE (明確或由 fuchsia.sysmem2/BufferCollection.SetConstraints 明確設為無條件) 就不能設定 vmo。constraints

2

vmo_usable_start

uint64

VMO 第一個可用位元組中的偏移。必須小於 VMO 的位元組大小，並在 VMO 結束之前保留足夠的 BufferMemorySettings.size_bytes 空間。

目前 sysmem 的這個欄位一律會設為 0，未來除非所有參與者明確指出支援非零的 vmo_usable_start (這項機制不存在於此註解)，否則 sysmem 不會將這個欄位設為非零值。如果參與者未明確指示支援非零 vmo_usable_start (所有目前的用戶端)，應間接假設這個欄位已設為 0，而不需實際檢查此欄位。

3

close_weak_asap

handle<eventpair>

如果 vmo 是 sysmem 的 VMO 控制代碼，此欄位會設定。用戶端必須將 close_weak_asap 保留為 vmo，且必須注意到 ZX_EVENTPAIR_PEER_CLOSED。如果發生這個信號，用戶端必須關閉 vmo 浮動式。如果不這樣做，用戶端就會視為 VMO 流失，而在這種情況下，sysmem 最終會透過 Syyslog 大聲表示 (目前為 5 秒)。

聯合國

Allocator_GetVmoInfo_Result 嚴格 資源

序數	Variant	類型
1	`response`	`Allocator_GetVmoInfo_Response`
2	`err`	`Error`
3	`framework_err`	`internal`

Allocator_ValidateBufferCollectionToken_Result 嚴格

序數	Variant	類型	說明
1	`response`	`Allocator_ValidateBufferCollectionToken_Response`
3	`framework_err`	`internal`

BufferCollectionTokenGroup_CreateChildrenSync_Result 嚴格 資源

序數	Variant	類型	說明
1	`response`	`BufferCollectionTokenGroup_CreateChildrenSync_Response`
3	`framework_err`	`internal`

BufferCollectionToken_DuplicateSync_Result 嚴格 資源

序數	Variant	類型	說明
1	`response`	`BufferCollectionToken_DuplicateSync_Response`
3	`framework_err`	`internal`

BufferCollection_CheckAllBuffersAllocations_Result 嚴格

序數	Variant	類型
1	`response`	`BufferCollection_CheckAllBuffersAllocated_Response`
2	`err`	`Error`
3	`framework_err`	`internal`

BufferCollection_WaitForAllBuffersAllocations_Result 嚴格 資源

序數	Variant	類型
1	`response`	`BufferCollection_WaitForAllBuffersAllocated_Response`
2	`err`	`Error`
3	`framework_err`	`internal`

Node_GetBufferCollectionId_Result 嚴格

序數	Variant	類型	說明
1	`response`	`Node_GetBufferCollectionId_Response`
3	`framework_err`	`internal`

Node_GetNodeRef_Result 嚴格 資源

序數	Variant	類型	說明
1	`response`	`Node_GetNodeRef_Response`
3	`framework_err`	`internal`

Node_IsAlternativeFor_Result 嚴格

序數	Variant	類型
1	`response`	`Node_IsAlternateFor_Response`
2	`err`	`Error`
3	`framework_err`	`internal`

Node_Sync_Result 嚴格