Fuchsia.sysmem

BufferCollection 是從參與者直接連線至 sysmem re。邏輯 BufferCollection；邏輯 BufferCollection 通常會與其他參與者共用。換句話說，BufferCollection 介面的執行個體是「邏輯緩衝區集合」的檢視畫面。

這個連線的作用是，在邏輯 BufferCollection 填入緩衝區時，以非同步方式指出。

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

此外，這個介面日後可能允許以其他方式指定限制，並可能允許在一定程度上來回協商限制。

這個介面日後可能允許每個 BufferCollection 有超過 64 個 VMO 控制代碼，但目前上限為 64 個。

這個介面日後可能允許分配/取消分配單一緩衝區。

部分啟動器可能會等待一小段時間，直到所有舊的邏輯 BufferCollection VMO 控制代碼關閉 (或直到短暫時間逾時)，再分配新的 BufferCollection，以協助控制實體記憶體片段，並避免新舊集合的緩衝區分配生命週期重疊。集合可能很大，因此值得避免分配重疊 (時間)。

已淘汰：23 新增：7

AttachLifetimeTracking

AttachLifetimeTracking：

AttachLifetimeTracking() 可讓用戶端等到舊的邏輯緩衝區集合完全或大部分取消分配後，再嘗試分配新的邏輯緩衝區集合。

將 eventpair 端點附加至邏輯緩衝區集合，這樣一來，當分配的緩衝區數量降至「buffers_remaining」時，server_end 就會關閉。server_end 則會在邏輯分配完成後關閉。

如果邏輯分配失敗，例如附加子樹狀結構 (使用 AttachToken())，則無論整體邏輯緩衝區集合中可能分配的緩衝區數量為何，server_end 都會在失敗期間關閉。

這個事件表示的生命週期包括已分配緩衝區的非同步清除作業，且只有在緩衝區 VMO 控制代碼的所有持有者都關閉這些 VMO 控制代碼後，才能執行這項非同步清除作業。因此，用戶端應注意不要永遠等待 ZX_EVENTPAIR_PEER_CLOSED 訊號，特別是使用邏輯緩衝區集合的任何參與者較不信任或較不可靠時。

buffers_remaining 參數可讓您等待所有緩衝區 (buffers_remaining 緩衝區除外) 完全取消分配。如果刻意不關閉已知數量的緩衝區，以便繼續使用資料，這種做法就很有用，例如即使影片串流使用受保護的輸出緩衝區，仍可在 UI 中顯示最後一個可用的影片畫面。判斷在不關閉的情況下可保留多少緩衝區，超出 BufferCollection 介面的範圍 (至少目前如此)，但通常會在 0 到 2 的範圍內。

這項機制旨在與提供類似 AttachLifetimeTracking() 機制的其他通訊協定相容，因為相同事件的重複項目可以傳送至多個 AttachLifetimeTracking()，且當所有生命週期結束條件都符合時 (所有重複項目的持有者都已關閉其控制代碼)，系統會發出 ZX_EVENTPAIR_PEER_CLOSED 信號。

附加作業無法取消。關閉 eventpair 的用戶端不會減少待處理的附加數量。

關閉用戶端不會導致伺服器採取任何動作。如果伺服器會監聽用戶端事件，則僅用於偵錯記錄。

伺服器會刻意不「信任」用戶端傳送的任何位元。這項機制刻意只使用 ZX_EVENTPAIR_PEER_CLOSED，無法提早觸發，只有在 server_end 的所有控制代碼都關閉時才會觸發。其他信號位元不具任何意義，用戶端應在功能上忽略事件配對或其對等端任一端的任何其他信號位元。

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

要求

名稱	類型
`server_end`	`handle<eventpair>`
`buffers_remaining`	`uint32`

AttachToken

如果現有集合的緩衝區數量、限制和參與者允許，請建立新的權杖，嘗試將新的參與者新增至現有集合。

這項功能可用於替換失敗的參與者，以及/或在緩衝區分配後新增/重新新增參與者。

附加權杖 / 集合失敗不會傳播至附加權杖的父項。失敗會從可有可無權杖的一般子項傳播到可有可無權杖。如果子項已附加，或子項可有可無，且在邏輯分配後發生失敗，則子項失敗不會影響父項。

在某些情況下，發起者可能會選擇先為參與者的特定執行個體使用可有可無的權杖，之後如果該參與者的第一個執行個體失敗，則可能會為該參與者的新第二個執行個體提供使用 AttachToken() 建立的權杖。

從 BufferCollectionToken 管道的用戶端角度來看，權杖的作用與其他權杖相同。用戶端可以視需要 Duplicate() 權杖，並將權杖傳送至其他程序。權杖應透過呼叫 BindSharedCollection()，正常轉換為 BufferCollection 管道。應在該 BufferCollection 管道上呼叫 SetConstraints()。

WaitForBuffersAllocated() 傳回成功結果，表示可以使用現有的緩衝區集合、已建立的 BufferCollectionInfo (包括圖片格式限制)，以及現有的其他參與者及其緩衝區數量，滿足新參與者的限制。如果結果為失敗，表示無法使用現有的緩衝區集合及其已邏輯分配的參與者，來滿足新參與者的限制。如果改為建立新的集合，則可能滿足所有參與者的限制，前提是使用 SetDispensable() 代替 AttachToken()，或使用一般權杖。

使用 AttachToken() 建立的權杖會對緩衝區集合中目前生效的所有限制、考慮中的附加權杖，以及附加權杖下的子權杖 (本身不是附加權杖或不屬於這類權杖) 執行限制匯總。

buffer_count 分配給 min_buffer_count_for_camping 等項目的順序是先到先得，但子項無法在所有父項傳送 SetConstraints() 之前分配。

另請參閱 SetDispensable()，與 AttachToken() 相反，它會讓建立的權杖 + 子項與其父項一起參與限制匯總。

新建立的權杖必須先 Sync() 至 sysmem，才能傳遞至 BindSharedCollection()。新權杖的 Sync() 可透過這個 BufferCollection 上的 BufferCollection.Sync() 完成。或者，也可以在新權杖上使用 BufferCollectionToken.Sync()。透過新建立的權杖傳送任何 BufferCollectionToken.Duplicate() 訊息後，即可啟動 BufferCollectionToken.Sync()，以便使用單一來回行程將這些額外權杖同步至 sysmem。

rights_attenuation_mask 的這些值不會導致衰減 (請注意，0 不在此清單中；0 會將 ERROR 輸出至系統記錄，協助診斷用戶端程式碼中的錯誤)：

ZX_RIGHT_SAME_RIGHTS (建議)
0xFFFFFFFF (計算衰減遮罩時，這個值合理)

要求

名稱	類型
`rights_attenuation_mask`	`uint32`
`token_request`	`server_end:BufferCollectionToken`

CheckBuffersAllocated

如果緩衝區集合已分配或失敗，則會傳回與 WaitForBuffersAllocated 相同的結果代碼；如果 WaitForBuffersAllocated 會封鎖，則會傳回 ZX_ERR_UNAVAILABLE。

要求

<EMPTY>

回應

名稱	類型
`status`	`zx/Result`

關閉

在 BufferCollectionToken 管道上：

一般來說，參與者會將 BufferCollectionToken 轉換為 BufferCollection 檢視畫面，但參與者也可以自由關閉權杖 (然後立即或稍後關閉管道，以回應伺服器關閉其端)，避免造成邏輯緩衝區收集失敗。一般來說，如果權杖管道意外關閉，會導致邏輯緩衝區收集失敗 (只有涉及 AttachToken() 或 SetDispensable() 的特定情況例外)。

在 BufferCollection 管道上：

根據預設，如果 BufferCollection 發生非預期的失敗，伺服器會將整個邏輯緩衝區集合視為失敗。部分原因是為了在任何參與者失敗時，加快關閉 VMO 控制代碼，以回收記憶體。如果參與者想要完全關閉 BufferCollection 檢視畫面，而不造成邏輯緩衝區集合失敗，可以在關閉 BufferCollection 管道的用戶端之前傳送 Close()。如果這是最後一個 BufferCollection 檢視畫面，邏輯緩衝區集合仍會消失。Close() 可以在 SetConstraints() 之前或之後發生。如果在 SetConstraints() 之前，緩衝區集合就不需要這個節點的限制，即可進行分配。如果在 SetConstraints() 之後，即使沒有管道連結，限制條件仍會保留，並與任何後續的邏輯分配彙整。

在 BufferCollectionTokenGroup 管道上：

根據預設，BufferCollectionTokenGroup 發生非預期失敗時，會觸發邏輯 BufferCollectionTokenGroup 失敗，並將失敗傳播至其父項。如要關閉 BufferCollectionTokenGroup 管道，而不導致邏輯群組失敗或傳播失敗，請在關閉管道用戶端端點前傳送 Close()。

如果 Close() 發生在 AllChildrenPresent() 之前，即使有 Close()，邏輯緩衝區集合仍會失敗 (因為 sysmem 無法確定是否已建立所有相關子項，因此不確定是否會向 sysmem 提供所有相關限制)。如果 Close() 發生在 AllChildrenPresent() 之後，子項及其所有限制都會保持不變 (就像 BufferCollectionTokenGroup 管道保持開啟一樣)，且關閉不會觸發或傳播失敗。

要求

<EMPTY>

GetNodeRef

這會取得事件控制代碼，可做為在任何節點上呼叫的 IsAlternateFor() 參數。用戶端不會獲得發出此事件信號的權利，因為這個控制代碼只能用來證明用戶端是從這個節點取得此控制代碼。

由於這是 get 而非 set，因此在 GetNodeRef() 和 IsAlternateFor() 呼叫之間不需要 Sync()，即使這兩個呼叫可能位於不同管道。

另請參閱 IsAlternateFor()。

要求

<EMPTY>

回應

名稱	類型
`node_ref`	`handle<event>`

IsAlternateFor

這會檢查呼叫節點是否位於子樹中，而該子樹的根節點是共同父項 BufferCollectionTokenGroup 的不同子項權杖，與傳入的 node_ref 相關。

這個呼叫用於協助准入控制簡化和偵錯。

node_ref 必須使用 BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup 的 GetNodeRef() 取得。

node_ref 可以是重複的控制代碼，因此不必在每次呼叫 IsAlternateFor() 時呼叫 GetNodeRef()。

如果呼叫權杖可能不是有效的權杖，因為權杖的提供者可能具有敵意/不受信任，請先呼叫 ValidateBufferCollectionToken()，而不是在 IsAlternateFor() 由於呼叫權杖不是真正的權杖 (未真正與 sysmem 通訊) 而未回應時，可能無限期卡住。另一個選項是先使用這個權杖呼叫 BindSharedCollection，這也會驗證權杖並將其轉換為 BufferCollection，然後呼叫 BufferCollection IsAlternateFor()。

錯誤值：

ZX_ERR_NOT_FOUND 表示在與呼叫節點相同的邏輯緩衝區集合中，找不到 node_ref。在邏輯分配之前，以及在同一個邏輯分配子樹中，這基本上表示 node_ref 從未屬於這個邏輯緩衝區集合，因為在邏輯分配之前，所有存在的 node_ref 都會至少保留到邏輯分配 (包括已執行 Close() 並關閉其管道)，而為了傳回 ZX_ERR_NOT_FOUND，這個節點的通道仍需在伺服器端連線，如果整個邏輯分配失敗，則不會發生這種情況。在邏輯分配之後或在不同的邏輯分配子樹中，可能還有其他原因會導致這項錯誤。舉例來說，不同的邏輯分配 (透過 AttachToken() 或 SetDispensable() 與這個節點的邏輯分配分開) 可能會導致其子樹狀結構刪除這些節點，或者可能存在 BufferCollectionTokenGroup，且可能選取與 node_ref 所在子樹狀結構不同的子樹狀結構，導致 node_ref 節點遭到刪除。只有在使用 Close() 且節點的子樹狀結構尚未失敗時，sysmem 才會在節點沒有對應管道後保留節點。另一個可能原因，是 node_ref 為具有足夠權限的 eventpair 控制代碼，但並非實際從 GetNodeRef() 取得的 node_ref。

ZX_ERR_INVALID_ARGS 表示呼叫端傳遞的 node_ref 不是 eventpair 控制代碼，或不具備實際 node_ref 預期的必要權限。

這項呼叫不會傳回其他失敗狀態碼。不過，sysmem 日後可能會新增其他程式碼，因此用戶端應針對任何失敗狀態碼，提供合理的預設處理方式。

成功時，is_alternate 的意義如下：

true - 呼叫節點和 node_ref 節點之間的第一個共同父節點是 BufferCollectionTokenGroup。這表示呼叫節點和 node_ref 節點不會同時套用兩者的限制，而是 sysmem 會選擇其中一個限制，絕不會同時套用兩者。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有該子項的子樹狀結構會影響限制匯總。
false - 呼叫節點和 node_ref 節點之間的第一個共同父項節點不是 BufferCollectionTokenGroup。目前，這表示第一個共同父節點是 BufferCollectionToken 或 BufferCollection (無論是否 Close()ed)。這表示如果任何相關的父項 BufferCollectionTokenGroup 選取了這兩個節點，則呼叫節點和 node_ref 節點可能會在邏輯分配的限制匯總期間套用其限制。在這種情況下，沒有任何 BufferCollectionTokenGroup 會直接阻止兩個節點同時被選取，以及兩者的限制同時被匯總，但即使為 false，如果一或兩個節點有直接或間接父項 BufferCollectionTokenGroup，且該父項選取了不包含呼叫節點或 node_ref 節點的子樹，則一或兩個節點仍可能從考量中排除。

要求

名稱	類型
`node_ref`	`handle<event>`

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

SetConstraints

為邏輯 BufferCollection 提供 BufferCollectionConstraints。

參與者只能呼叫 SetConstraints() 一次。

有時，發起者只是想留意成功/失敗，以便填入緩衝區，並在失敗時顯示 zx.Status。在這種情況下，has_constraints 可以是 false，系統會忽略 constraints。

如果用戶端傳送空值限制，系統不會提供 VMO 控制代碼給用戶端，這可能是因為啟動器不需要 VMO 控制代碼。沒有 VMO 控制代碼不會妨礙啟動器調整緩衝區的哪個部分視為有效和類似，但啟動器無法保留 VMO 控制代碼，以防止邏輯 BufferCollection 在邏輯 BufferCollection 需要消失時清除，無論啟動器的參與程度為何。

如要嘗試填入緩衝區，BufferCollection 用戶端管道的所有持有者都必須先呼叫 SetConstraints()，sysmem 才會嘗試分配緩衝區。

has_constraints如果為 false，則限制條件實際上為空值，且系統會忽略 constraints。空值限制的傳送者不會在 BufferCollectionInfo 中取得任何 VMO 控制代碼，但仍可找出分配的緩衝區數量，並仍可透過 buffer_index 參照緩衝區。

constraints 是緩衝區集合的限制。

要求

名稱	類型
`has_constraints`	`bool`
`constraints`	`BufferCollectionConstraints`

SetDebugClientInfo

設定目前用戶端的相關資訊，供 sysmem 用於偵錯記憶體流失，以及等待限制時停止運作的問題。|name| 可以是任意字串，但目前的程序名稱 (請參閱 fsl::GetCurrentProcessName()) 是不錯的預設值。|id| 可以是任意 ID，但目前的程序 ID (請參閱 fsl::GetCurrentProcessKoid()) 是不錯的預設值。

啟用詳細記錄功能時 (請參閱 SetVerboseLogging())，也會使用這個名稱，指出哪個用戶端先關閉管道，導致子樹狀結構失敗 (如果子樹狀結構的目的已達成，這可能是正常現象，但如果比預期早發生，從 sysmem 的角度來看，用戶端管道專屬名稱可協助診斷失敗最初來源)。

根據預設 (除非遭到這則訊息覆寫，或使用 Allocator.SetDebugClientInfo())，節點會在建立子節點時，從父節點複製資訊。雖然這可能比什麼都沒有好，但通常最好讓每位參與者使用 Node.SetDebugClientInfo() 或 Allocator.SetDebugClientInfo()，直接保留與目前用戶端相關的資訊。此外，如果懷疑節點含有從父項複製的資訊，可以使用 SetVerboseLogging() 協助釐清。

要求

名稱	類型
`name`	`string:64`
`id`	`uint64`

SetDebugTimeoutLogDeadline

如果並非所有用戶端都在建立集合後 5 秒內設定限制，Sysmem 會記錄警告。用戶端可以呼叫這個方法，變更記錄列印的時間。如果有多個用戶端設定期限，則無法指定哪個期限會生效。

要求

名稱	類型
`deadline`	`zx/Time`

SetName

為這個緩衝區集合中的 VMO 設定名稱。名稱可能會縮短。名稱只會影響設定後分配的 VMO，這項呼叫不會重新命名現有的 VMO。如果多個用戶端設定不同名稱，則優先順序值較大者勝出。

要求

名稱	類型
`priority`	`uint32`
`name`	`string:64`

SetVerboseLogging

詳細記錄包含每個用戶端透過 SetConstraints() 設定的限制、透過 SetDebugClientInfo() 設定的資訊，以及節點樹狀結構。

一般來說，sysmem 只會在匯總失敗時顯示一行申訴，其中僅包含匯總失敗的具體詳細原因，以及最少的背景資訊。如果只進行小幅變更，且系統在變更前正常運作，這通常足以診斷問題，但對於首次讓新的緩衝區集合運作，通常沒有特別幫助。尤其是涉及 AttachToken()、SetDispensable()、BufferCollectionTokenGroup 節點和相關節點子樹等項目的複雜節點樹，詳細記錄功能有助於診斷樹狀結構的外觀、邏輯分配失敗的原因，或樹狀結構或子樹提早失敗的原因。

額外記錄的目的，是為了在效能方面達到可接受的程度，但前提是只在少數緩衝區集合上啟用。如果我們並未追蹤錯誤，就不應傳送這則訊息。

如果太多參與者啟用詳細記錄功能，我們可能需要透過其他設定，允許系統層級的 sysmem 詳細記錄功能，避免 sysmem 因這則訊息而產生過多記錄。

如果我們不信任某個節點，無法讓該節點啟用詳細記錄功能，則對於某些節點，這可能是 NOP，因為與該節點相關聯的政策是刻意設定的。

要求

<EMPTY>

同步

確認伺服器端已收到先前的訊息，包括權杖、集合或群組上的 Duplicate() 訊息。

如果對無效的 sysmem 權杖呼叫 BufferCollectionToken.Sync()，Sync() 可能會永久停止運作。請參閱 ValidateBufferCollectionToken()，瞭解如何以一次來回的成本，降低惡意/假 BufferCollectionToken 的可能性。另一種方法是將權杖傳遞至 BindSharedCollection()，這也會驗證權杖，並將其交換為 BufferCollection 管道，然後即可使用 BufferCollection Sync()。

Sync() 之後，就可以放心地將 token_request 的用戶端傳送給其他參與者，因為伺服器會在其他參與者將權杖傳送至 BindSharedCollection() 時辨識權杖。

其他選項包括等待每個 token.Duplicate() 個別完成 (在每個 token.Sync() 之後使用個別呼叫)，或在透過 BindSharedCollection() 提交權杖後，在 BufferCollection 上呼叫 Sync()。

另一種緩解方法是避免在權杖上呼叫 Sync()，而是在原始權杖無效時，處理 BufferCollection.Sync() 可能發生的失敗。從效能的角度來看，這個選項可能較佳，但用戶端程式碼必須延遲傳送從這個權杖複製的權杖，直到用戶端程式碼將複製的權杖轉換為 BufferCollection，並收到 BufferCollection.Sync() 的成功回應。

建議您盡可能改用 BufferCollection.Sync() (請參閱上文)。如果無法使用 BufferCollection.Sync()，呼叫端必須知道這個權杖有效，否則 BufferCollectionToken.Sync() 可能會永久停止回應。如果尚未確認權杖是否有效，請先參閱 ValidateBufferCollectionToken()，檢查權杖是否有效。

要求

<EMPTY>

回應

<EMPTY>

WaitForBuffersAllocated

緩衝區分配完成後，這項要求就會完成。如果嘗試分配但失敗，則會傳回一些失敗詳細資料。

必須先完成下列事項，系統才會分配緩衝區：

邏輯 BufferCollectionToken 的所有 BufferCollectionToken 都必須透過 BindSharedCollection() 提交。
邏輯 BufferCollection 的所有 BufferCollection 都必須已傳送 SetConstraints()。

如果成功，則傳回 ZX_OK。如果要求有效，但因資源耗盡而無法執行，則傳回 ZX_ERR_NO_MEMORY。如果呼叫端無權取得要求的緩衝區，則傳回 ZX_ERR_ACCESS_DENIED。如果要求格式錯誤，則傳回 ZX_ERR_INVALID_ARGS。如果要求有效但無法滿足 (可能是因為硬體限制)，則傳回 ZX_ERR_NOT_SUPPORTED。

buffer_collection_info 包含 VMO 控制代碼和其他相關資訊。

要求

<EMPTY>

回應

名稱	類型
`status`	`zx/Result`
`buffer_collection_info`	`BufferCollectionInfo_2`

BufferCollectionToken

BufferCollectionToken 不是 BufferCollection，而是在分配 BufferCollection 之前，用來識別潛在共用 BufferCollection 的方法。

我們使用 BufferCollectionToken 的管道，而非單一事件配對 (配對)，因為這樣可以偵測錯誤狀況，例如參與者在建立過程中死亡。

fuchsia.sysmem.BufferCollectionToken 類型尚未淘汰，因為目前仍用於其他通訊協定，但 fuchsia.sysmem.BufferCollectionToken 的所有內部項目都已淘汰。權杖管道會同時提供 fuchsia.sysmem.BufferCollectionToken 和 fuchsia.sysmem2.BufferCollectionToken。

其他通訊協定將權杖欄位切換至 fuchsia.sysmem2.BufferCollectionToken 後，這個通訊協定就會淘汰。

新增：7

關閉

在 BufferCollectionToken 管道上：

在 BufferCollection 管道上：

在 BufferCollectionTokenGroup 管道上：

要求

<EMPTY>

CreateBufferCollectionTokenGroup

大多數 sysmem 用戶端和許多參與者都不需要關心這則訊息，或 BufferCollectionTokenGroup(s) 的一般情況。

BufferCollectionTokenGroup 可用於在 N 個子權杖中建立 1 of N OR。在匯總期間未選取的子權杖會失敗 (關閉)，潛在參與者應在 BufferCollection 管道用戶端端點看到 PEER_CLOSED 時注意到這一點，讓參與者可以清除未發生的推測性使用 (類似於一般 BufferCollection 伺服器端在邏輯緩衝區集合失敗時關閉)。

請參閱通訊協定 BufferCollectionTokenGroup 的註解。

如要將任何 rights_attenuation_mask 或 AttachToken()/SetDispensable() 套用至整個群組，可以使用專為此目的設計的權杖，做為群組的直接父項。

group_request：BufferCollectionTokenGroup 管道的伺服器端，由 sysmem 提供服務。

已淘汰：23 已新增：9

要求

名稱	類型
`group_request`	`server_end:BufferCollectionTokenGroup`

複製

您可以使用這個方法，在建立共用 BufferCollection 之前新增參與者。只有在效能敏感的情況下，才應使用此方法取代 DuplicateSync，因為在這種情況下，不適合等待 sysmem 回應每個重複項目。

傳送一或多則 Duplicate() 訊息後，以及將建立的權杖傳送給其他參與者 (或其他分配器管道) 之前，用戶端應傳送 Sync() 並等待回應。您可以在權杖上呼叫 Sync()，或將這個權杖傳遞至 BindSharedCollection()，在取得的 BufferCollection 上呼叫 Sync()。無論是哪一種方式，都能確保伺服器在其他參與者透過獨立配置器管道將權杖傳送至伺服器之前，就知道透過 Duplicate() 建立的權杖。

所有權杖都必須透過 BindSharedCollection() 或 Close() 提交，才能成功建立 BufferCollection。

當用戶端呼叫 BindSharedCollection() 來提交 BufferCollectionToken 時，伺服器會先處理所有 Duplicate() 訊息，然後再關閉 BufferCollectionToken。這樣一來，用戶端就能 Duplicate() 並立即使用 BindSharedCollection 提交 BufferCollectionToken，然後將 token_request 的用戶端轉移給其他參與者。伺服器會先注意到 token_request 的存在，然後才將這個 BufferCollectionToken 視為完全關閉。

這個遮罩中為零的 rights_attenuation_mask 權限位元，不會出現在透過 token_request 用戶端取得的緩衝區 VMO 權限中。這樣一來，發起者或中介參與者就能削弱參與者可用的權利。這項功能不會授予參與者原本沒有的權限。ZX_RIGHT_SAME_RIGHTS 值可用來指定不應套用任何衰減。

rights_attenuation_mask 的下列值不會導致衰減：

ZX_RIGHT_SAME_RIGHTS (建議)
0xFFFFFFFF (計算衰減遮罩時，這個值合理)
0 (已淘汰，請勿使用 0，否則記錄中會出現錯誤)

token_request 是 BufferCollectionToken 管道的伺服器端。這個管道的用戶端端點會做為另一個參與者，建立共用的 BufferCollection。

已淘汰：23 新增：7

要求

名稱	類型
`rights_attenuation_mask`	`uint32`
`token_request`	`server_end:BufferCollectionToken`

DuplicateSync

您可以使用這個方法，在建立共用 BufferCollection 之前新增更多參與者。系統會為 rights_attenuation_masks 陣列中的每個項目傳回新的權杖。傳回值是每個新參與者權杖的用戶端端點。

如果呼叫權杖可能並非有效權杖 (因為權杖提供者可能不友善/不受信任)，請考慮先使用 ValidateBufferCollectionToken()，而不是在 DuplicateSync() 因呼叫權杖並非實際權杖而未回應時，可能無限期卡住。

與 Duplicate() 不同，呼叫這個方法後不需要 Sync() (請參閱「通訊協定節點」)。

所有權杖都必須透過 BindSharedCollection() 或 Close() 提交，才能成功建立 BufferCollection。

在 rights_attenuation_masks 的每個項目中，如果權限位元為零，則無法透過對應的傳回權杖取得緩衝區 VMO 權限。這樣一來，發起者或中介參與者就能削弱參與者可用的權利。這項功能不會授予參與者原本沒有的權限。ZX_RIGHT_SAME_RIGHTS 值可用來指定不應套用任何衰減。

已淘汰：23 新增：7

要求

名稱	類型
`rights_attenuation_masks`	`vector<zx/Rights>:64`

回應

名稱	類型
`tokens`	`vector<client_end:BufferCollectionToken>:64`

GetNodeRef

由於這是 get 而非 set，因此在 GetNodeRef() 和 IsAlternateFor() 呼叫之間不需要 Sync()，即使這兩個呼叫可能位於不同管道。

另請參閱 IsAlternateFor()。

要求

<EMPTY>

回應

名稱	類型
`node_ref`	`handle<event>`

IsAlternateFor

這會檢查呼叫節點是否位於子樹中，而該子樹的根節點是共同父項 BufferCollectionTokenGroup 的不同子項權杖，與傳入的 node_ref 相關。

這個呼叫用於協助准入控制簡化和偵錯。

node_ref 必須使用 BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup 的 GetNodeRef() 取得。

node_ref 可以是重複的控制代碼，因此不必在每次呼叫 IsAlternateFor() 時呼叫 GetNodeRef()。

錯誤值：

ZX_ERR_INVALID_ARGS 表示呼叫端傳遞的 node_ref 不是 eventpair 控制代碼，或不具備實際 node_ref 預期的必要權限。

這項呼叫不會傳回其他失敗狀態碼。不過，sysmem 日後可能會新增其他程式碼，因此用戶端應針對任何失敗狀態碼，提供合理的預設處理方式。

成功時，is_alternate 的意義如下：

true - 呼叫節點和 node_ref 節點之間的第一個共同父節點是 BufferCollectionTokenGroup。這表示呼叫節點和 node_ref 節點不會同時套用兩者的限制，而是 sysmem 會選擇其中一個限制，絕不會同時套用兩者。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有該子項的子樹狀結構會影響限制匯總。
false - 呼叫節點和 node_ref 節點之間的第一個共同父項節點不是 BufferCollectionTokenGroup。目前，這表示第一個共同父節點是 BufferCollectionToken 或 BufferCollection (無論是否 Close()ed)。這表示如果任何相關的父項 BufferCollectionTokenGroup 選取了這兩個節點，則呼叫節點和 node_ref 節點可能會在邏輯分配的限制匯總期間套用其限制。在這種情況下，沒有任何 BufferCollectionTokenGroup 會直接阻止兩個節點同時被選取，以及兩者的限制同時被匯總，但即使為 false，如果一或兩個節點有直接或間接父項 BufferCollectionTokenGroup，且該父項選取了不包含呼叫節點或 node_ref 節點的子樹，則一或兩個節點仍可能從考量中排除。

要求

名稱	類型
`node_ref`	`handle<event>`

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

SetDebugClientInfo

要求

名稱	類型
`name`	`string:64`
`id`	`uint64`

SetDebugTimeoutLogDeadline

要求

名稱	類型
`deadline`	`zx/Time`

SetDispensable

在邏輯上分配緩衝區後，可有可無的權杖可能會失敗，但不會導致其父項 (如有) 失敗。

在分配邏輯緩衝區之前，可有可無的權杖會與其父項一起參與限制匯總。如果可有可無的權杖在邏輯上分配緩衝區之前失敗，失敗就會傳播到可有可無的權杖的父項。

緩衝區在邏輯上分配完畢後，可有可無的權杖 (或其任何子項) 失敗時，不會傳播至可有可無權杖的父項。失敗會從可有可無權杖的一般子項傳播到可有可無權杖。如果子項已附加，或子項可有可無，且在邏輯分配後發生失敗，則子項失敗不會影響父項。

如果參與者需要提供限制，但緩衝區分配後，參與者可能會失敗，但不會導致父項的緩衝區收集失敗，則可以使用可有可無的權杖。

相較之下，AttachToken() 可用於建立不與父項參與限制匯總的權杖，且其失敗不會傳播至父項，且其延遲提供限制不會阻止父項完成緩衝區分配。

如果用戶端使用這則訊息，則不應依賴用戶端自己的 BufferCollectionToken 或 BufferCollection 管道，從伺服器端關閉，因為用戶端已 SetDispensable() 並提供給其他程序的任何 BufferCollectionToken 或 BufferCollection 突然失敗。因此，用戶端應特別注意，透過其他方式留意其他程序是否失敗。

雖然可以在 BufferCollectionTokenGroup 的直接子項上 SetDispensable() (且可能有用)，但之後無法使用 AttachToken() 將群組直接子項的失敗可有可無權杖替換為新權杖 (因為群組上沒有 AttachToken())。在這種情況下，如要啟用 AttachToken() 替代功能，請建立額外的非可有可無權杖 (節點)，做為群組的直接子項，並將現有的可有可無權杖設為額外權杖 (節點) 的子項。這樣一來，群組直接子項的額外權杖 (節點) 就會具有 BufferCollection.AttachToken()，可用來取代失敗的可有可無權杖。

對已可捨棄的權杖呼叫 SetDispensable()，會產生冪等效果。

已淘汰：23 新增：7

要求

<EMPTY>

SetName

要求

名稱	類型
`priority`	`uint32`
`name`	`string:64`

SetVerboseLogging

詳細記錄包含每個用戶端透過 SetConstraints() 設定的限制、透過 SetDebugClientInfo() 設定的資訊，以及節點樹狀結構。

額外記錄的目的，是為了在效能方面達到可接受的程度，但前提是只在少數緩衝區集合上啟用。如果我們並未追蹤錯誤，就不應傳送這則訊息。

如果太多參與者啟用詳細記錄功能，我們可能需要透過其他設定，允許系統層級的 sysmem 詳細記錄功能，避免 sysmem 因這則訊息而產生過多記錄。

如果我們不信任某個節點，無法讓該節點啟用詳細記錄功能，則對於某些節點，這可能是 NOP，因為與該節點相關聯的政策是刻意設定的。

要求

<EMPTY>

同步

確認伺服器端已收到先前的訊息，包括權杖、集合或群組上的 Duplicate() 訊息。

Sync() 之後，就可以放心地將 token_request 的用戶端傳送給其他參與者，因為伺服器會在其他參與者將權杖傳送至 BindSharedCollection() 時辨識權杖。

要求

<EMPTY>

回應

<EMPTY>

BufferCollectionTokenGroup

sysmem 實作保證與邏輯/概念模型一致，如下所示：

一般來說，邏輯分配會考量根節點和所有與根節點連線且不傳輸 AttachToken() 的節點，或以 AttachToken() 權杖為根節點的子樹，以及所有與該子樹連線且不傳輸其他 AttachToken() 的節點。這稱為邏輯分配剪除子樹，簡稱剪除子樹。

在限制匯總期間，每個 BufferCollectionTokenGroup 都會從子項中選取一個子權杖。其餘子項會顯示邏輯分配失敗，而所選子項則可能成功。

如果整體邏輯分配修剪子樹中有多個 BufferCollectionTokenGroup，則兩個群組之間的相對優先順序，等同於樹狀結構 DFS 預先排序疊代中的順序，其中父項的優先順序高於子項，左側子項的優先順序高於右側子項。

選取群組的特定子項時 (無論是在限制匯總嘗試期間暫時選取，還是最終選取)，未選取群組的其他子項可能會「隱藏」這些未選取子項下的其他群組。

在邏輯分配中，系統會先嘗試匯總，暫時選取最高優先順序群組的子項 0，以及下一個最高優先順序群組的子項 0 (未被暫時選取的群組隱藏)，依此類推。

如果該匯總嘗試失敗，系統會嘗試匯總所有相同群組的序數 0 子項，但優先順序最低的非隱藏群組除外，該群組會暫時選取其序數 1 子項 (然後是子項 2，依此類推)。如果暫時選取項目更新後，新的最低優先順序群組取消隱藏，系統會先依序考量該群組的所有子項，再變更先前最低優先順序群組中的暫時選取項目。就結果而言，這相當於以類似計數的順序，系統化列舉所有可能的選擇組合，最常更新優先順序最低的群組，最不常更新優先順序最高的群組。我們不必實際嘗試所有組合的匯總，而是可以略過因隱藏而多餘/等效的組合，而不會對結果造成任何變更。

系統會繼續嘗試匯總列舉的非等效選項組合，直到 (a) 所有匯總嘗試都失敗，導致整體邏輯分配失敗，或 (b) 嘗試匯總成功，此時會嘗試分配緩衝區 (如有需要)。如果根據首次成功匯總的緩衝區分配失敗，則整體邏輯分配失敗 (不會重試 / 重新嘗試緩衝區分配)。如果緩衝區分配成功 (或不需要)，邏輯分配就會成功。

如果這個優先順序配置不適用於您的 sysmem 使用方式，請與 sysmem 團隊聯絡，討論是否能新增方法來滿足您的需求。

請避免為每個邏輯分配建立大量 BufferCollectionTokenGroup，尤其是整體子項數量龐大，且使用序數 0 子項(可能還有後續子項) 匯總時，可能經常失敗的情況。我們預計透過以下方式，降低評估過多群組中過多子組合/選項時，可能產生的時間複雜度：當考量的群組子組合/選項數量超過特定上限 (相當高，但並非極大) 時，邏輯分配就會失敗。我們認為，更進階 (且更複雜) 的緩解措施在實務上並非必要，也不值得增加複雜度。如果達到或預計會達到上限，請與 sysmem 團隊聯絡，討論可能的解決方案。

如果可行，建議在單一 BufferCollectionConstraints 中使用多個 ImageFormatConstraints (當參與者只需要表示能使用多個 PixelFormat，並由 sysmem 選擇所有參與者支援的 PixelFormat 時)。

與 BufferCollectionToken 和 BufferCollection 類似，如果關閉 BufferCollectionTokenGroup 管道時未先傳送 Close()，會導致邏輯緩衝區集合失敗 (如果使用 SetDispensable() 或 AttachToken()，且 BufferCollectionTokenGroup 是這類節點下子樹的一部分，則會導致子樹失敗，而不會將失敗傳播至其父項)。

已淘汰：23 已新增：9

AllChildrenPresent

AllChildrenPresent()

建立所有子項後，用戶端必須呼叫 AllChildrenPresent()，通知 sysmem 不會再建立子項，這樣 sysmem 就能知道何時可以開始匯總限制。

如要傳送 Close()，應在 AllChildrenPresent() 之後傳送，否則仍會觸發群組失敗，並將失敗傳播至群組的父項。

要求

<EMPTY>

關閉

在 BufferCollectionToken 管道上：

在 BufferCollection 管道上：

在 BufferCollectionTokenGroup 管道上：

要求

<EMPTY>

CreateChild

建立子權杖。將這個權杖的用戶端傳遞至 BindSharedCollection() 之前，必須先在 CreateChild() 之後完成 Sync()。或者，用戶端可以使用 CreateChildrenSync()，這基本上包含 Sync()。

token_request：新權杖管道的伺服器端。

rights_attenuation_mask - 如果是 ZX_RIGHT_SAME_RIGHTS，建立的權杖可讓持有者取得與父項權杖 (群組) 相同的緩衝區權限。

要求

名稱	類型
`payload`	`BufferCollectionTokenGroupCreateChildRequest`

CreateChildrenSync

一次同步建立 1 或多個子權杖。與 CreateChild() 不同的是，您不需要先完成 Sync()，就能將傳回權杖的用戶端傳遞至 BindSharedCollection()。

rights_attentuation_mask 的大小會決定建立的子權杖數量。

索引較低的子項權杖優先順序較高 (會較早嘗試)，索引較高的子項權杖優先順序較低。

與所有子權杖一樣，成功匯總後，系統會從所有建立的子項中選擇一個子項 (在可能多次呼叫 CreateChild() 和 CreateChildrenSync() 時建立的所有子項)。

每個群組的子項總數上限，以及整個樹狀結構 (從根節點開始) 的節點總數上限，都受到限制，無法透過這些通訊協定設定。

要求

名稱	類型
`rights_attenuation_masks`	`vector<zx/Rights>:64`

回應

名稱	類型
`tokens`	`vector<client_end:BufferCollectionToken>:64`

GetNodeRef

由於這是 get 而非 set，因此在 GetNodeRef() 和 IsAlternateFor() 呼叫之間不需要 Sync()，即使這兩個呼叫可能位於不同管道。

另請參閱 IsAlternateFor()。

要求

<EMPTY>

回應

名稱	類型
`node_ref`	`handle<event>`

IsAlternateFor

這會檢查呼叫節點是否位於子樹中，而該子樹的根節點是共同父項 BufferCollectionTokenGroup 的不同子項權杖，與傳入的 node_ref 相關。

這個呼叫用於協助准入控制簡化和偵錯。

node_ref 必須使用 BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup 的 GetNodeRef() 取得。

node_ref 可以是重複的控制代碼，因此不必在每次呼叫 IsAlternateFor() 時呼叫 GetNodeRef()。

錯誤值：

ZX_ERR_INVALID_ARGS 表示呼叫端傳遞的 node_ref 不是 eventpair 控制代碼，或不具備實際 node_ref 預期的必要權限。

這項呼叫不會傳回其他失敗狀態碼。不過，sysmem 日後可能會新增其他程式碼，因此用戶端應針對任何失敗狀態碼，提供合理的預設處理方式。

成功時，is_alternate 的意義如下：

true - 呼叫節點和 node_ref 節點之間的第一個共同父節點是 BufferCollectionTokenGroup。這表示呼叫節點和 node_ref 節點不會同時套用兩者的限制，而是 sysmem 會選擇其中一個限制，絕不會同時套用兩者。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有該子項的子樹狀結構會影響限制匯總。
false - 呼叫節點和 node_ref 節點之間的第一個共同父項節點不是 BufferCollectionTokenGroup。目前，這表示第一個共同父節點是 BufferCollectionToken 或 BufferCollection (無論是否 Close()ed)。這表示如果任何相關的父項 BufferCollectionTokenGroup 選取了這兩個節點，則呼叫節點和 node_ref 節點可能會在邏輯分配的限制匯總期間套用其限制。在這種情況下，沒有任何 BufferCollectionTokenGroup 會直接阻止兩個節點同時被選取，以及兩者的限制同時被匯總，但即使為 false，如果一或兩個節點有直接或間接父項 BufferCollectionTokenGroup，且該父項選取了不包含呼叫節點或 node_ref 節點的子樹，則一或兩個節點仍可能從考量中排除。

要求

名稱	類型
`node_ref`	`handle<event>`

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

SetDebugClientInfo

要求

名稱	類型
`name`	`string:64`
`id`	`uint64`

SetDebugTimeoutLogDeadline

要求

名稱	類型
`deadline`	`zx/Time`

SetName

要求

名稱	類型
`priority`	`uint32`
`name`	`string:64`

SetVerboseLogging

詳細記錄包含每個用戶端透過 SetConstraints() 設定的限制、透過 SetDebugClientInfo() 設定的資訊，以及節點樹狀結構。

額外記錄的目的，是為了在效能方面達到可接受的程度，但前提是只在少數緩衝區集合上啟用。如果我們並未追蹤錯誤，就不應傳送這則訊息。

如果太多參與者啟用詳細記錄功能，我們可能需要透過其他設定，允許系統層級的 sysmem 詳細記錄功能，避免 sysmem 因這則訊息而產生過多記錄。

如果我們不信任某個節點，無法讓該節點啟用詳細記錄功能，則對於某些節點，這可能是 NOP，因為與該節點相關聯的政策是刻意設定的。

要求

<EMPTY>

同步

確認伺服器端已收到先前的訊息，包括權杖、集合或群組上的 Duplicate() 訊息。

Sync() 之後，就可以放心地將 token_request 的用戶端傳送給其他參與者，因為伺服器會在其他參與者將權杖傳送至 BindSharedCollection() 時辨識權杖。

要求

<EMPTY>

回應

<EMPTY>

節點

已淘汰：23 已新增：9

關閉

在 BufferCollectionToken 管道上：

在 BufferCollection 管道上：

在 BufferCollectionTokenGroup 管道上：

要求

<EMPTY>

GetNodeRef

由於這是 get 而非 set，因此在 GetNodeRef() 和 IsAlternateFor() 呼叫之間不需要 Sync()，即使這兩個呼叫可能位於不同管道。

另請參閱 IsAlternateFor()。

要求

<EMPTY>

回應

名稱	類型
`node_ref`	`handle<event>`

IsAlternateFor

這會檢查呼叫節點是否位於子樹中，而該子樹的根節點是共同父項 BufferCollectionTokenGroup 的不同子項權杖，與傳入的 node_ref 相關。

這個呼叫用於協助准入控制簡化和偵錯。

node_ref 必須使用 BufferCollectionToken、BufferCollection 或 BufferCollectionTokenGroup 的 GetNodeRef() 取得。

node_ref 可以是重複的控制代碼，因此不必在每次呼叫 IsAlternateFor() 時呼叫 GetNodeRef()。

錯誤值：

ZX_ERR_INVALID_ARGS 表示呼叫端傳遞的 node_ref 不是 eventpair 控制代碼，或不具備實際 node_ref 預期的必要權限。

這項呼叫不會傳回其他失敗狀態碼。不過，sysmem 日後可能會新增其他程式碼，因此用戶端應針對任何失敗狀態碼，提供合理的預設處理方式。

成功時，is_alternate 的意義如下：

true - 呼叫節點和 node_ref 節點之間的第一個共同父節點是 BufferCollectionTokenGroup。這表示呼叫節點和 node_ref 節點不會同時套用兩者的限制，而是 sysmem 會選擇其中一個限制，絕不會同時套用兩者。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有該子項的子樹狀結構會影響限制匯總。
false - 呼叫節點和 node_ref 節點之間的第一個共同父項節點不是 BufferCollectionTokenGroup。目前，這表示第一個共同父節點是 BufferCollectionToken 或 BufferCollection (無論是否 Close()ed)。這表示如果任何相關的父項 BufferCollectionTokenGroup 選取了這兩個節點，則呼叫節點和 node_ref 節點可能會在邏輯分配的限制匯總期間套用其限制。在這種情況下，沒有任何 BufferCollectionTokenGroup 會直接阻止兩個節點同時被選取，以及兩者的限制同時被匯總，但即使為 false，如果一或兩個節點有直接或間接父項 BufferCollectionTokenGroup，且該父項選取了不包含呼叫節點或 node_ref 節點的子樹，則一或兩個節點仍可能從考量中排除。

要求

名稱	類型
`node_ref`	`handle<event>`

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

SetDebugClientInfo

要求

名稱	類型
`name`	`string:64`
`id`	`uint64`

SetDebugTimeoutLogDeadline

要求

名稱	類型
`deadline`	`zx/Time`

SetName

要求

名稱	類型
`priority`	`uint32`
`name`	`string:64`

SetVerboseLogging

詳細記錄包含每個用戶端透過 SetConstraints() 設定的限制、透過 SetDebugClientInfo() 設定的資訊，以及節點樹狀結構。

額外記錄的目的，是為了在效能方面達到可接受的程度，但前提是只在少數緩衝區集合上啟用。如果我們並未追蹤錯誤，就不應傳送這則訊息。

如果太多參與者啟用詳細記錄功能，我們可能需要透過其他設定，允許系統層級的 sysmem 詳細記錄功能，避免 sysmem 因這則訊息而產生過多記錄。

如果我們不信任某個節點，無法讓該節點啟用詳細記錄功能，則對於某些節點，這可能是 NOP，因為與該節點相關聯的政策是刻意設定的。

要求

<EMPTY>

同步

確認伺服器端已收到先前的訊息，包括權杖、集合或群組上的 Duplicate() 訊息。

Sync() 之後，就可以放心地將 token_request 的用戶端傳送給其他參與者，因為伺服器會在其他參與者將權杖傳送至 BindSharedCollection() 時辨識權杖。

要求

<EMPTY>

回應

<EMPTY>

SecureMem

SecureMem

用戶端為 sysmem。伺服器是 securemem 驅動程式庫。

TEE：受信任的執行環境。

REE - Rich Execution Environment。

啟用 sysmem 呼叫 securemem 驅動程式庫，取得透過 TEE (或 securemem 驅動程式) 設定的任何安全堆積，並設定透過 sysmem 設定的任何實體安全堆積。

目前，動態分配的安全堆積是透過 sysmem 設定，因為它在啟動期間很早就開始，且可以成功保留連續的實體記憶體。目前，固定位置的安全堆積是透過 TEE 設定，因為管道是從系統啟動載入程式到 TEE。不過，這項通訊協定刻意不區分哪些堆積是動態分配，哪些是固定位置。

已淘汰：23 新增：7

AddSecureHeapPhysicalRange

sysmem 向 securemem 驅動程式庫提出的這項要求，會傳達要新增的實體範圍，適用於透過 sysmem 設定實體範圍的堆積。

只有 sysmem 可以呼叫這個函式，因為只有 sysmem 會透過 RegisterSecureMem() 取得提供這個通訊協定的 FIDL 管道用戶端。securemem 驅動程式庫程式是這個通訊協定的伺服器端。

securemem 驅動程式庫必須先將所有涵蓋的偏移量設為受保護，才能成功回應這則訊息。

如果失敗，securemem 驅動程式必須確保未建立受保護的範圍。

如果 dynamic_protection_ranges 為 false，Sysmem 最多只能呼叫一次。

如果 dynamic_protection_ranges 為 true，只要目前的範圍數量不超過 max_protected_range_count，sysmem 就能多次呼叫此函式。

呼叫端不得嘗試新增與現有範圍相符的範圍。新增的範圍可以彼此重疊，但不能完全相同。

錯誤：

ZX_ERR_BAD_STATE - 在 !dynamic_protection_ranges 時呼叫多次。新增堆積會導致整體堆積數量超過 max_protected_range_count。
ZX_ERR_INVALID_ARGS - 堆積不符合預期，或範圍不符合 protected_range_granularity。* ZX_ERR_INTERNAL - 一般內部錯誤 (例如與 TEE 通訊時，未產生 zx_status_t 錯誤)。
也可能發生其他錯誤，例如通訊失敗或 zx_status_t 失敗的伺服器傳播。

要求

名稱	類型
`heap_range`	`SecureHeapAndRange`

回應

名稱	類型
`payload`	`SecureMem_AddSecureHeapPhysicalRange_Result`

DeleteSecureHeapPhysicalRange

sysmem 向 securemem 驅動程式庫發出的這項要求，會傳達要刪除的實體範圍，適用於透過 sysmem 設定實體範圍的堆積。

securemem 驅動程式庫必須先將所有涵蓋的偏移量設為未受保護，才能成功回應這則訊息。

如果失敗，securemem 驅動程式必須確保受保護的範圍未刪除。

如果 dynamic_protection_ranges 為 false，Sysmem 不得呼叫此函式。

如果 dynamic_protection_ranges 為 true，sysmem 可以在呼叫時存在的各種範圍內，重複呼叫這個函式。

如果刪除的範圍有任何部分未涵蓋在其他受保護範圍內，則對整個範圍任何部分進行中的 DMA 可能會中斷 / 失敗，且可能干擾整個系統 (匯流排鎖定或類似情況，視裝置詳細資料而定)。因此，呼叫端必須確保沒有任何進行中的 DMA 發生在要刪除的範圍內，除非呼叫端有其他有效範圍涵蓋要刪除範圍的每個區塊。刪除作業不會影響到與刪除範圍外區塊之間的 DMA。

錯誤： * ZX_ERR_BAD_STATE - 在 !dynamic_protection_ranges 時呼叫。 * ZX_ERR_INVALID_ARGS - 堆積不符合預期，或範圍不符合 protected_range_granularity。

ZX_ERR_INTERNAL - 一般內部錯誤 (例如與 TEE 通訊時，未產生 zx_status_t 錯誤)。
ZX_ERR_NOT_FOUND - 找不到指定範圍。
也可能發生其他錯誤，例如通訊失敗或 zx_status_t 失敗的伺服器傳播。

要求

名稱	類型
`heap_range`	`SecureHeapAndRange`

回應

名稱	類型
`payload`	`SecureMem_DeleteSecureHeapPhysicalRange_Result`

GetPhysicalSecureHeapProperties

這項從 sysmem 傳送至 securemem 驅動程式庫的要求，會取得受保護/安全堆積的屬性。

這項功能只會處理具有單一連續實體範圍的堆積。

系統會指出堆積的整個實體範圍，以防這項要求需要一些實體空間，才能自動偵測有多少範圍可供 REE 使用。這項要求完成前，系統會刪除所有臨時 HW 保護範圍。

新增：7

要求

名稱	類型
`entire_heap`	`SecureHeapAndRange`

回應

名稱	類型
`payload`	`SecureMem_GetPhysicalSecureHeapProperties_Result`

GetPhysicalSecureHeaps

取得任何安全堆積的實體位址和長度，其物理範圍是透過 TEE 設定。

目前，這些是固定的實體位址和長度，位置會透過 TEE 傳送。

如果不需要任何特殊的堆積專屬 VMO 設定或拆除，建議使用這個方法，而非 ['fuchsia.hardware.sysmem.Sysmem/RegisterHeap']。

securemem 驅動程式庫必須先由 TEE 保護實體範圍，才能成功回應這項要求。

Sysmem 應只呼叫一次。傳回零個堆積不代表失敗。

錯誤： * ZX_ERR_BAD_STATE - 呼叫超過一次。 * ZX_ERR_INTERNAL - 一般內部錯誤 (例如與 TEE 通訊時，未產生 zx_status_t 錯誤)。

不允許其他錯誤；任何其他錯誤都應視為 ZX_ERR_INTERNAL。

要求

<EMPTY>

回應

名稱	類型
`payload`	`SecureMem_GetPhysicalSecureHeaps_Result`

ModifySecureHeapPhysicalRange

sysmem 向 securemem 驅動程式庫提出的這項要求，會傳達要修改的實體範圍，以及新的基準和長度，適用於透過 sysmem 設定實體範圍的堆積。

securemem 驅動程式庫必須將範圍設為僅涵蓋新的偏移量，才能成功回應這則訊息。

如果失敗，securemem 驅動程式必須確保範圍未變更。

如果 dynamic_protection_ranges 為 false，Sysmem 不得呼叫此函式。如果 !is_mod_protected_range_available，Sysmem 不得呼叫此函式。

如果 dynamic_protection_ranges 為 true，sysmem 可以在呼叫時存在的各種範圍內，重複呼叫這個函式。

範圍只能在其中一端修改，不能同時修改兩端。如果範圍縮短，且未涵蓋的區塊未涵蓋在其他有效範圍內，則對整個縮短範圍進行的任何進行中 DMA 都可能失敗，進而中斷整個系統 (匯流排鎖定或類似情況)，因此呼叫端必須確保沒有任何 DMA 正在對縮短範圍的任何部分進行，除非修改此範圍而未涵蓋的區塊都涵蓋在其他有效範圍內，在這種情況下，不會中斷進行中的 DMA。

如果範圍修改後長度 <= 0，就會遭到刪除。

錯誤： * ZX_ERR_BAD_STATE - 在 !dynamic_protection_ranges 時呼叫。 * ZX_ERR_INVALID_ARGS - 意外的堆積，或 old_range 或 new_range 不符合 protected_range_granularity，或 old_range 和 new_range 的開頭和結尾都不同 (不允許)。

ZX_ERR_INTERNAL - 一般內部錯誤 (例如與 TEE 通訊時，未產生 zx_status_t 錯誤)。
ZX_ERR_NOT_FOUND - 找不到指定範圍。
也可能發生其他錯誤，例如通訊失敗或 zx_status_t 失敗的伺服器傳播。

要求

名稱	類型
`range_modification`	`SecureHeapAndRangeModification`

回應

名稱	類型
`payload`	`SecureMem_ModifySecureHeapPhysicalRange_Result`

ZeroSubRange

將透過 AddSecureHeapPhysicalRange() 新增的現有實體範圍子範圍歸零。子範圍必須完全由一個實體範圍涵蓋，且不得與任何其他實體範圍重疊。

is_covering_range_explicit - 如果為 true，涵蓋範圍必須是透過 AddSecureHeapPhysicalRange() 明確建立的其中一個範圍，且可能已修改。如果為 false，涵蓋範圍不得是透過 AddSecureHeapPhysicalRange() 明確建立的範圍之一，但涵蓋範圍必須存在，且不是透過 AddSecureHeapPhysicalRange() 建立。涵蓋範圍通常是 TEE 設定的堆積的整個實體範圍 (或涵蓋範圍更廣)，且其設定會透過 GetPhysicalSecureHeaps() 傳送至 sysmem。

這項要求不會中斷進行中的 DMA。

要求

名稱	類型
`is_covering_range_explicit`	`bool`
`heap_range`	`SecureHeapAndRange`

回應

名稱	類型
`payload`	`SecureMem_ZeroSubRange_Result`

STRUCTS

BufferCollectionConstraints

BufferCollection 參數的限制。您可以為每位參與者指定這些限制。sysmem 服務會匯總多個參與者的限制。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	說明	預設
`usage`	`BufferUsage`	用途僅做為提示，協助 sysmem 在有多個相容選項時，選擇更合適的 PixelFormat 或類似選項。匯總 BufferCollectionConstraints 時，這些值會進行位元 OR 運算。除非整個 BufferCollectionConstraints 因 !has_constraints 而在邏輯上為空值，否則至少須指定一個用量位元。	無預設值
`min_buffer_count_for_camping`	`uint32`	參與者可同時保留供其專用的緩衝區數量 (非暫時性，即 camp on)。舉例來說，視訊解碼器會指定 (至少) 參考影格數量上限 + 1 個目前解碼的影格。參與者不得佔用超過此處指定的緩衝區 (除非時間極短)，否則處理程序可能會卡住。匯總 BufferCollectionConstraints 時，系統會將這些值相加。在測試情境中，如果長時間佔用超過這個數量的緩衝區，可能 (理想情況下會) 標記為失敗。在測試情境中，參與者可能不會同時獲得超過這個數量的緩衝區。	無預設值
`min_buffer_count_for_dedicated_slack`	`uint32`	每個參與者因鬆弛原因所需的緩衝區數量下限，以便更好地重疊處理 / 提高效能。匯總 BufferCollectionConstraints 時，系統會將這些值相加。參與者通常應在此指定 0 或 1。如果 min_buffer_count_for_camping 已足以讓參與者在稍微落後時保持 100% 的忙碌狀態，則通常適合指定 0。如果比 min-camping 嚴格需要的緩衝區多 1 個，就能提供足夠的緩衝時間，讓參與者保持 100% 的忙碌狀態 (在稍微落後時，相較於沒有額外緩衝區時的較低百分比)，則適合指定 1。在測試情境中，這個欄位可能會強制設為 0，所有參與者應會繼續運作，不會卡住。如果因向前進度而需要緩衝區，則應在 min_buffer_count_for_camping 中考量該緩衝區。	無預設值
`min_buffer_count_for_shared_slack`	`uint32`	與 min_buffer_count_for_dedicated_slack 類似，但匯總這些值時，會使用 max (而非 add)。這裡的值不會與任何參與者的 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 中考量該緩衝區。	無預設值
`min_buffer_count`	`uint32`	特別挑剔的參與者可能需要要求嚴格的 buffer_count 範圍，甚至是特定的 buffer_count。除非參與者確實必須設定這個欄位，以限制整體 BufferCollectionInfo_2.buffer_count，否則這個欄位應維持 0。這類參與者仍應填寫上述 min_buffer_count_for_* 欄位。	無預設值
`max_buffer_count`	`uint32`	0 會視為 0xFFFFFFFF。	無預設值
`has_buffer_memory_constraints`	`bool`	BufferCollectionSettings.buffer_settings 的限制。如果參與者打算指定 image_format_constraints_count > 1，通常會透過 image_format_constraints 隱含指定緩衝區大小下限，並可能只透過 buffer_memory_constraints 指定緩衝區大小上限。	無預設值
`buffer_memory_constraints`	`BufferMemoryConstraints`		無預設值
`image_format_constraints_count`	`uint32`	BufferCollection 緩衝區中儲存的圖片，其圖片格式參數的選用限制。包括像素格式和圖片版面配置。這些限制是依像素格式設定，因此可以設定多個限制。清單中的項目必須有不重複的 pixel_formats。匯總時，系統只會保留所有參與者指定的像素格式，且 image_format_constraints_count 不為零 (且不為 Null) 的 BufferCollectionConstraints。	無預設值
`image_format_constraints`	`array<ImageFormatConstraints, 32>`		無預設值

資源

定義於 fuchsia.sysmem/collections_deprecated.fidl

已淘汰。請使用 ['fuchsia.sysmem2.BufferCollectionInfo']。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	說明	預設
`buffer_count`	`uint32`	集合中的緩衝區數量。	無預設值
`format`	`BufferFormat`	說明緩衝區內容的表示方式。集合中的所有緩衝區都採用相同格式。	無預設值
`vmos`	`array<handle<vmo>?, 64>`	集合中每個緩衝區的 VMO 控制代碼。只有在緩衝區由 VMO 支援時，才會顯示 VMO。如果存在，`buffer_count` 之後的所有 VMO 都是無效控制代碼。所有緩衝區 VMO 控制代碼的大小和存取權限都相同。 VMO 存取權取決於用戶端在分配緩衝區集合時指定的用途。舉例來說，如果用戶端表示唯讀用途，則會收到沒有寫入權限的 VMO。	無預設值
`vmo_size`	`uint64`	每個 VMO 的大小。只有在緩衝區由 VMO 支援時，才會顯示這個屬性。	0

資源

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

已淘汰：23 新增：7

欄位類型說明預設

buffer_count

uint32

緩衝區總數。

無預設值

settings

SingleBufferSettings

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

無預設值

buffers

array<VmoBuffer, 64>

集合中每個緩衝區的 VMO 控制代碼 (和 vmo_usable_start 偏移)。

如果存在，則索引 buffer_count 或之後的所有 VMO 都是無效 (0) 控制代碼。

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

VMO 存取權取決於用戶端在分配緩衝區集合時指定的用途。舉例來說，如果用戶端表示唯讀用途，則會收到沒有寫入權限的 VMO。此外，也可以透過 BufferCollectionToken.Duplicate() 呼叫的參數，減少權限。

無預設值

BufferFormat

定義於 fuchsia.sysmem/formats_deprecated.fidl

說明緩衝區內容的表示方式。各類緩衝區會以專屬表格說明。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	說明	預設
`tag`	`uint32`	由於這個結構體原本是單一成員聯集，因此我們保留了標記，避免變更任何線路格式。標記必須設為 `0`，其他值都不正確。	0
`image`	`ImageFormat`		無預設值

BufferMemoryConstraints

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	說明	預設
`min_size_bytes`	`uint32`		0
`max_size_bytes`	`uint32`	0 會視為 0xFFFFFFFF。	4294967295
`physically_contiguous_required`	`bool`		否
`secure_required`	`bool`	如果設為 true，至少有一位參與者需要安全記憶體。匯總 BufferCollectionConstraints 時，這些值會進行布林 OR 運算。	否
`ram_domain_supported`	`bool`	根據預設，參與者必須確保 CPU 可以在沒有快取作業的情況下，讀取或寫入資料至緩衝區。如果支援使用 RAM 網域，資料必須在 RAM 中可用 (CPU 快取狀態，使 RAM 資料不會因髒 CPU 快取行將不正確的資料寫入 RAM 而損毀)，且使用 CPU 讀取的消費者必須在讀取前使 CPU 快取失效 (生產者不保證零過時「乾淨」快取行)	否
`cpu_domain_supported`	`bool`		true
`inaccessible_domain_supported`	`bool`		否
`heap_permitted_count`	`uint32`	選用的堆積限制。如果參與者不在意分配到哪個堆積記憶體，請將這個欄位留空。	無預設值
`heap_permitted`	`array<HeapType, 32>`		無預設值

BufferMemorySettings

已淘汰：23 新增：7

欄位	類型	說明	預設
`size_bytes`	`uint32`		無預設值
`is_physically_contiguous`	`bool`		無預設值
`is_secure`	`bool`		無預設值
`coherency_domain`	`CoherencyDomain`		無預設值
`heap`	`HeapType`	分配緩衝區的特定堆積。請參閱本檔案上方，瞭解堆積 ID 值。	無預設值

BufferUsage

定義於 fuchsia.sysmem/usages.fidl

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

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	預設
`none`	`uint32`	無預設值
`cpu`	`uint32`	無預設值
`vulkan`	`uint32`	無預設值
`display`	`uint32`	無預設值
`video`	`uint32`	無預設值

ColorSpace

說明圖片中的像素應如何呈現。簡單的色域只需要類型。參數色域可能需要額外屬性。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	說明	預設
`type`	`ColorSpaceType`		無預設值

FormatModifier

定義於 fuchsia.sysmem/format_modifier.fidl

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位類型說明預設

value

uint64

前 8 個位元是 FormatModifierVendor 列舉中分配的供應商代碼。較低的 56 位元由供應商定義。

基於相容性考量，這個欄位和欄位中的值會以這種方式定義。

無預設值

ImageFormat

定義於 fuchsia.sysmem/image_formats_deprecated.fidl

說明圖片的呈現方式。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	說明	預設
`width`	`uint32`	資料列寬度 (以像素為單位)。	無預設值
`height`	`uint32`	列數。	無預設值
`layers`	`uint32`	多層映像檔中的層數。如未指定，預設值為 1。	1
`pixel_format`	`PixelFormat`	Pixel 格式。已淘汰：23 新增：7	無預設值
`color_space`	`ColorSpace`	色域。已淘汰：23 新增：7	無預設值
`planes`	`array<ImagePlane, 4>`	已淘汰：23 新增：7	無預設值

ImageFormatConstraints

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

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	說明	預設
`pixel_format`	`PixelFormat`	適用下列限制的 PixelFormat。參與者可能支援多個 PixelFormat，在這種情況下，參與者可以使用 ImageFormatConstraints 清單，其中每個 PixelFormat 都有一個項目。ImageFormatConstraints 的其他欄位因 PixelFormat 而異的情況並不少見，例如線性格式支援的大小上限小於圖塊格式。	無預設值
`color_spaces_count`	`uint32`	空白會視為錯誤。重複的項目會視為錯誤。任意排序並非錯誤。	無預設值
`color_space`	`array<ColorSpace, 32>`		無預設值
`min_coded_width`	`uint32`	允許的最小寬度 (以像素為單位)。舉例來說，影片解碼器參與者可將這個欄位設為串流可能指定的最小 coded_width。相較之下，required_min_coded_width 則會設為串流目前指定的 coded_width。min_coded_width 會取最大值進行匯總，required_min_coded_width 則會取最小值進行匯總。另請參閱 required_min_coded_width。	無預設值
`max_coded_width`	`uint32`	寬度上限 (以像素為單位)。例如，Scenic 可能會將這個欄位 (直接或透過子參與者) 設為可合成的最大寬度。0 會視為 0xFFFFFFFF。	無預設值
`min_coded_height`	`uint32`	高度下限 (以像素為單位)。舉例來說，影片解碼器參與者可能會將這個欄位設為串流指定的 coded_height。	無預設值
`max_coded_height`	`uint32`	高度上限 (以像素為單位)。例如，Scenic 可能會將這個欄位 (直接或透過子參與者) 設為可合成的最大高度。0 會視為 0xFFFFFFFF。	無預設值
`min_bytes_per_row`	`uint32`	必須大於或等於平面 0 的 min_coded_width 所隱含的值。	無預設值
`max_bytes_per_row`	`uint32`	必須大於或等於平面 0 的 max_coded_width 所隱含的值。 0 會視為 0xFFFFFFFF。	無預設值
`max_coded_width_times_coded_height`	`uint32`	圖片區域的最大像素數會透過 BufferSettings.size_bytes 間接限制，也可以透過這個欄位直接強制執行。0 會視為 0xFFFFFFFF。	4294967295
`layers`	`uint32`	多層映像檔中的層數。0 會視為 1。	1
`coded_width_divisor`	`uint32`	coded_width % width_divisor 必須為 0。 0 會視為 1。	1
`coded_height_divisor`	`uint32`	coded_height % height_divisor 必須為 0。 0 會視為 1。	1
`bytes_per_row_divisor`	`uint32`	bytes_per_row % bytes_per_row_divisor 必須為 0。0 會視為 1。	1
`start_offset_divisor`	`uint32`	vmo_usable_start % start_offset_divisor 必須為 0。0 會視為 1。	1
`display_width_divisor`	`uint32`	display_width % display_width_divisor 必須為 0。 0 會視為 1。	1
`display_height_divisor`	`uint32`	display_height % display_height_divisor 必須為 0。 0 會視為 1。	1
`required_min_coded_width`	`uint32`	required_ dimension bounds. 與開頭不含「required_」的對應欄位相比，這些欄位 (設為非零值時) 表示一項要求，即產生的匯總 non-required_ 欄位指定一個空間，該空間完全包含每個參與者 required_ 欄位表示的空間。舉例來說，生產者影片解碼器非常樂意讓消費者接受任何內容，且影片解碼器不希望限制串流中可能出現且消費者可接受的潛在維度空間，但影片解碼器必須確保產生的維度範圍至少包含從串流解碼的目前維度。同樣地，如果發起者有特定的動態維度情境，可能會希望事先要求參與者同意至少處理發起者在該情境中預期的維度範圍 (否則會提早失敗，而不是稍後失敗，可能會嘗試使用較小的 required_space 再次嘗試)。這些欄位通常由產生者或發起者設定，而非取用者。非 required_ 欄位會透過交集匯總，而 required_ 欄位則會透過聯集匯總。如果設定，required_max_coded_width 和 required_max_coded_height 會導致分配的緩衝區足夠大，可以容納 required_max_coded_width * required_max_coded_height 的圖片。 TODO(dustingreen)：簡化分配最小緩衝區的程序，該緩衝區也可以 (選用) 處理最大尺寸的 90 度旋轉版本 / 另一個主要顯示比例的替代必要邊界。0 會視為 0xFFFFFFFF。	無預設值
`required_max_coded_width`	`uint32`		無預設值
`required_min_coded_height`	`uint32`	0 會視為 0xFFFFFFFF。	無預設值
`required_max_coded_height`	`uint32`		無預設值
`required_min_bytes_per_row`	`uint32`	0 會視為 0xFFFFFFFF。	無預設值
`required_max_bytes_per_row`	`uint32`		無預設值

ImageFormat_2

說明圖片的呈現方式。

這個類型已不適用於新程式碼，但部分相機程式碼和 StreamProcessor 仍會使用 (目前)。

欄位	類型	說明	預設
`pixel_format`	`PixelFormat`	Pixel 格式。	無預設值
`coded_width`	`uint32`	緩衝區中資料列的寬度 (以像素為單位)。必須大於或等於 display_width。可以小於 stride_bytes 隱含的寬度。	無預設值
`coded_height`	`uint32`	列數。必須大於或等於 display_height。	無預設值
`bytes_per_row`	`uint32`	平面 0 的跨距 (以位元組為單位)。平面 0 以外的平面 (如有，視 pixel_format 而定) 與平面 0 的步幅有已知的固定關係。如果是 Intel 拼貼紋理，步幅是指線性化版本的紋理。	無預設值
`display_width`	`uint32`	要顯示的資料列寬度 (以像素為單位)。這個值可以 <= coded_width。裁剪會發生在圖片右側 (而非左側)。	無預設值
`display_height`	`uint32`	要顯示的列數。這個值可以 <= coded_height，底部 (而非頂部) 可進行任何裁剪。	無預設值
`layers`	`uint32`	多層映像檔中的層數。	1
`color_space`	`ColorSpace`	色域。	無預設值
`has_pixel_aspect_ratio`	`bool`	pixel_aspect_ratio_width : pixel_aspect_ratio_height 是亮度 (又稱 Y) 樣本的像素顯示比例 (又稱樣本顯示比例，即 SAR)。pixel_aspect_ratio 為 1:1 表示方形像素。如果 pixel_aspect_ratio 為 2:1，表示像素的顯示寬度是高度的兩倍。轉碼器實作應確保這兩個值相對質，方法是在必要時減少分數 (兩者都除以 GCF)。當 has_pixel_aspect_ratio == false 時，pixel_aspect_ratio 為未知。在某些情況下，預設值 1:1 可能合適，但消費者一如往常，可以透過 OOB 方式判斷實際的 pixel_aspect_ratio。	否
`pixel_aspect_ratio_width`	`uint32`		1
`pixel_aspect_ratio_height`	`uint32`		1

ImagePlane

定義於 fuchsia.sysmem/image_formats_deprecated.fidl

這個類型已淘汰，且沒有直接替代項目 (刻意)，因為 fuchsia.images2 不需要個別描述每個平面。

已淘汰：23 新增：7

欄位	類型	說明	預設
`byte_offset`	`uint32`	平面起點與圖片起點之間的位元組偏移量。	無預設值
`bytes_per_row`	`uint32`	每列的步幅 (以位元組為單位)。僅適用於線性緩衝區格式。	無預設值

ImageSpec

定義於 fuchsia.sysmem/image_formats_deprecated.fidl

說明分配所需形式圖片的限制。

已淘汰：23 新增：7

欄位	類型	說明	預設
`min_width`	`uint32`	寬度下限 (以像素為單位)。	無預設值
`min_height`	`uint32`	高度下限 (以像素為單位)。	無預設值
`layers`	`uint32`	多層映像檔中的層數。如未指定，預設值為 1。	1
`pixel_format`	`PixelFormat`	Pixel 格式。	無預設值
`color_space`	`ColorSpace`	色域。	無預設值

Node_IsAlternateFor_Response

欄位	類型	說明	預設
`is_alternate`	`bool`		無預設值

PixelFormat

說明圖片中像素的呈現方式。簡單格式只需要類型。參數像素格式可能需要額外屬性。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

欄位	類型	說明	預設
`type`	`PixelFormatType`		無預設值
`has_format_modifier`	`bool`	這個 bool 實際上會將 format_modifier 設為選用，以滿足「ForDeprecatedCBindings」和「FIDL 簡易 C 繫結」。	無預設值
`format_modifier`	`FormatModifier`		無預設值

SecureMem_AddSecureHeapPhysicalRange_Response

<EMPTY>

SecureMem_DeleteSecureHeapPhysicalRange_Response

<EMPTY>

SecureMem_GetPhysicalSecureHeapProperties_Response

欄位	類型	說明	預設
`properties`	`SecureHeapProperties`		無預設值

SecureMem_GetPhysicalSecureHeaps_Response

欄位	類型	說明	預設
`heaps`	`SecureHeapsAndRanges`		無預設值

SecureMem_ModifySecureHeapPhysicalRange_Response

<EMPTY>

SecureMem_ZeroSubRange_Response

<EMPTY>

SingleBufferInfo 資源

目前沒有這種類型的替代方案，但如果您的用途需要在單一集合中分配遞增緩衝區，請與我們聯絡。

已淘汰：23 新增：7

欄位	類型	說明	預設
`settings`	`SingleBufferSettings`		無預設值
`buffer`	`VmoBuffer`		無預設值

SingleBufferSettings

初始緩衝區分配完成後，可以關閉舊緩衝區並分配新緩衝區。分配新的緩衝區時，其設定可能與集合中的其他緩衝區不同，而單一緩衝區的設定會透過 OnSingleBufferAllocated() 使用這個結構體傳送：

已淘汰：23 新增：7

欄位類型說明預設

buffer_settings BufferMemorySettings 無預設值

has_image_format_constraints

bool

如果緩衝區保留的資料不是未壓縮的圖片資料，就不會設定這個欄位。如果緩衝區保留的資料是未壓縮的圖片資料，可能會設定這個欄位。

至少目前，變更 PixelFormat 需要重新分配緩衝區。

無預設值

image_format_constraints ImageFormatConstraints 無預設值

VmoBuffer 資源

已淘汰：23 新增：7

欄位類型說明預設

vmo

handle<vmo>?

多個 CodecBuffer (僅限相同 buffer_lifetime_ordinal) 可使用同一個 VMO，但每個 VMO 控制代碼必須是獨立的控制代碼。

如果這是 BufferCollectionInfo_2 中等於或超過 BufferCollectionInfo_2.buffer_count 的 VmoBuffer，vmo 欄位可以是 0。

無預設值

vmo_usable_start

uint64

第一個可用位元組在 VMO 中的偏移量。必須小於 VMO 的大小 (以位元組為單位)，並在 VMO 結束前為 BufferMemorySettings.size_bytes 預留足夠的空間。

無預設值

列舉

CoherencyDomain strict

類型：uint32

「無法存取」僅適用於無法透過 CPU 存取緩衝區的情況。即使 secure_required 緩衝區只能在 CPU 處於安全模式 (或類似模式) 時由 CPU 存取，secure_required 緩衝區仍可具有 CoherencyDomain Cpu 或 Ram。相較之下，CPU 無法存取的裝置本機記憶體則為 CoherencyDomain Inaccessible，即使可以讓裝置 (實體或虛擬) 將資料從 Inaccessible 緩衝區複製到 CPU 可見的緩衝區，也是如此。

已淘汰：23 新增：7

名稱	值	說明
CPU	`0`
RAM	`1`
INACCESSIBLE	`2`

ColorSpaceType strict

類型：uint32

這份清單會為每個色域標準變體提供個別項目。

因此，如果我們新增對 709 RGB 變體的支援，就會在清單中為該變體新增獨立項目。2020 或 2100 的 RGB 變體也是如此。2020 的 YcCbcCrc 變體也是如此。2100 的 ICtCp 變體也是如此。

指定的 ColorSpaceType 可能允許與 PixelFormatType 搭配使用，後者提供的每樣本位元數與 ColorSpaceType 的官方規格相容。不一定支援所有符合規格的組合。請參閱 ImageFormatIsSupportedColorSpaceForPixelFormat()，瞭解最佳支援程度，但該函式傳回「true」並不保證任何指定的參與者組合，都能支援所需的 ColorSpaceType 和 PixelFormatType 組合。

sysmem 服務可協助找出雙方支援的組合，並分配適當的緩衝區。

ColorSpaceType 的規格不會隱含擴充，以支援標準外的每樣本位元數 (R、G、B 或 Y 樣本)。舉例來說，2020 和 2100 不支援每 Y 樣本 8 位元 (由 sysmem 支援)，因為 2020 或 2100 的規格中沒有每 Y 樣本 8 位元。如果 sysmem 參與者嘗試宣告支援非標準的 PixelFormat + ColorSpace，sysmem 會拒絕該組合，且無法分配 (刻意如此，以強烈不建議指定定義不足的組合)。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

名稱	值	說明
無效	`0`	色域類型無效。
SRGB	`1`	sRGB
REC601_NTSC	`2`	601 NTSC (「525 行」) YCbCr 原色，窄
REC601_NTSC_FULL_RANGE	`3`	601 NTSC (「525 線」) YCbCr 原色，寬
REC601_PAL	`4`	601 PAL (「625 行」) YCbCr 原色，窄
REC601_PAL_FULL_RANGE	`5`	601 PAL (「625 線」) YCbCr 原色，寬
REC709	`6`	709 YCbCr (非 RGB)
REC2020	`7`	2020 YCbCr (非 RGB，非 YcCbcCrc)
REC2100	`8`	2100 YCbCr (非 RGB、非 ICtCp)
PASS_THROUGH	`9`	像素格式不代表顏色，或位於應用程式專屬的色彩空間，無法由這個列舉中的其他項目描述。
DO_NOT_CARE	`4294967294`	sysmem 用戶端明確指出，sysmem 用戶端不在意選擇 / 使用哪個色域。新增：10

HeapType strict

類型：uint64

已知堆積類型。裝置專屬類型應設定位元 60。最高位元為保留位元，不應設定。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

名稱	值	說明
SYSTEM_RAM	`0`
AMLOGIC_SECURE	`1152921504606912512`	用於 amlogic 受保護記憶體的堆積。
AMLOGIC_SECURE_VDEC	`1152921504606912513`	在解密和影片解碼之間，用於 amlogic 受保護記憶體的堆積。
GOLDFISH_DEVICE_LOCAL	`1152921504606978048`	Goldfish Vulkan 用於裝置本機記憶體的堆積。
GOLDFISH_HOST_VISIBLE	`1152921504606978049`	Goldfish Vulkan 用於主機可見記憶體的堆積。
FRAMEBUFFER	`1152921504607043585`	用於顯示訊框緩衝區的堆積。這項功能適用於顯示卡驅動程式，僅限位於特定實體位址的單一影格緩衝區。有了 framebuffer 堆積，就能為 framebuffer 建立緩衝區集合，並在這些驅動程式中啟用 sysmem 支援。

PixelFormatType strict

類型：uint32

格式名稱中的通道順序反映了管道的實際版面配置。

每個值都與可包含的色域有關 (與 Vulkan 相反)。

這項設定應與 fuchsia.sysmem2.PixelFormatType 保持同步。

這個類型已不適用於新程式碼，但仍用於部分相機程式碼。

名稱	值	說明
無效	`0`
R8G8B8A8	`1`	僅限 RGB，每個 R/G/B/A 樣本 8 位元與 VK_FORMAT_R8G8B8A8_UNORM 相容。
BGRA32	`101`	32bpp BGRA，1 個平面。僅限 RGB，每個 B/G/R/A 樣本 8 位元。與 VK_FORMAT_B8G8R8A8_UNORM 相容。
I420	`102`	僅限 YUV，每個 Y 樣本 8 位元與 VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM 相容。
M420	`103`	僅限 YUV，每個 Y 樣本 8 位元與任何 Vulkan 格式不相容。
NV12	`104`	僅限 YUV，每個 Y 樣本 8 位元與 VK_FORMAT_G8_B8R8_2PLANE_420_UNORM 相容。
YUY2	`105`	僅限 YUV，每個 Y 樣本 8 位元與 VK_FORMAT_G8B8G8R8_422_UNORM 相容。
MJPEG	`106`
YV12	`107`	僅限 YUV，每個 Y 樣本 8 位元與 VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM 相容。U 平面可能位於圖片的 B 或 R 平面 (V 平面也一樣)；排序方式可透過查看 `VkBufferCollectionPropertiesFUCHSIA.samplerYcbcrConversionComponents` 的成員來決定。
BGR24	`108`	24bpp BGR，1 個平面。僅限 RGB，每個 B/G/R 樣本 8 位元與 VK_FORMAT_B8G8R8_UNORM 相容。
RGB565	`109`	16bpp RGB，1 個平面。5 位元 R、6 位元 G、5 位元 B 與 VK_FORMAT_R5G6B5_UNORM_PACK16 相容。
RGB332	`110`	8bpp RGB，1 個平面。3 位元 R、3 位元 G、2 位元 B 與任何 Vulkan 格式不相容。
RGB2220	`111`	8bpp RGB，1 個平面。2 位元 R、2 位元 G、2 位元 B 與任何 Vulkan 格式不相容。
L8	`112`	8bpp，僅限亮度 (紅色、綠色和藍色具有相同的值)。與 VK_FORMAT_R8_UNORM 相容。
R8	`113`	8bpp，僅限紅色 (綠色和藍色應解讀為 0)。與 VK_FORMAT_R8_UNORM 相容。
R8G8	`114`	16bpp RG，1 個平面。8 位元 R、8 位元 G。與 VK_FORMAT_R8G8_UNORM 相容。
A2R10G10B10	`115`	32bpp RGBA，1 個平面。2 位元 A、10 位元 R/G/B。與 VK_FORMAT_A2R10G10B10_UNORM_PACK32 相容。
A2B10G10R10	`116`	32bpp BGRA，1 個平面。2 位元 A、10 位元 R/G/B。與 VK_FORMAT_A2B10G10R10_UNORM_PACK32 相容。
DO_NOT_CARE	`4294967294`	sysmem 用戶端明確指出，sysmem 用戶端不在意選擇 / 使用哪種像素格式。設定這個值時，sysmem 用戶端不得設定 format_modifier_value。新增：10

TABLES

BufferCollectionTokenGroupCreateChildRequest 資源

序數	欄位	類型	說明
1	`token_request`	`server_end:BufferCollectionToken`	必須設定。
2	`rights_attenuation_mask`	`uint32`	如未設定，預設值為 ZX_RIGHT_SAME_RIGHTS。

SecureHeapAndRange

已淘汰：23 新增：7

序數	欄位	類型	說明
1	`heap`	`HeapType`
2	`range`	`SecureHeapRange`

SecureHeapAndRangeModification

已淘汰：23 新增：7

序數	欄位	類型
1	`heap`	`HeapType`
2	`old_range`	`SecureHeapRange`
3	`new_range`	`SecureHeapRange`

SecureHeapAndRanges

已淘汰：23 新增：7

序數	欄位	類型	說明
1	`heap`	`HeapType`	這是安全/受保護的堆積。
2	`ranges`	`vector<SecureHeapRange>:128`	實體範圍清單。這份清單必須依 physical_address 排序 (由低到高)，且不得有任何重疊的範圍。允許直接相鄰的範圍 (不重疊)。

SecureHeapProperties

已淘汰：23 新增：7

序數	欄位	類型	說明
1	`heap`	`HeapType`	為了方便您操作，以下再次提供 HeapType。
2	`dynamic_protection_ranges`	`bool`	如果為 true，則允許對同一個堆積多次呼叫 SetPhysicalSecureHeap()。如果為 false，則只能呼叫一次 SetPhyscialSecureHeap()，且不得呼叫 DeleteSecureHeapPhysicalRange() 或 ModifySecureHeapPhysicalRange()。即使這個值為 false，如果受保護的範圍在熱重新啟動期間不會清除，SecureMem 伺服器 (驅動程式庫) 仍須在熱重新啟動前取消保護。
3	`protected_range_granularity`	`uint32`	保護範圍的精細程度。如果開始時間的精細程度與結束時間或長度的精細程度不同，則這是這些值中的最大精細程度值。這個值必須是 2 的乘冪。用戶端不得要求指定較小精細程度的範圍。即使硬體可以執行更小的精細度，這個值也必須至少為 zx_system_page_size()。
4	`max_protected_range_count`	`uint64`	如果 SecureMem 伺服器需要進行這類模擬，則不應計算 SecureMem 伺服器內部使用的保留範圍，以便從範圍組合 A 取得範圍組合 B。一般來說，SecureMem 伺服器不需要進行這類模擬。如果 SecureMem 伺服器保留任何範圍，SecureMem 用戶端就無法使用這些保留範圍。如果範圍數量僅受可用記憶體限制，SecureMem 伺服器可以為這個值回報 0xFFFFFFFFFFFFFFFF。但仍須設定欄位。和往常一樣，SecureMem 伺服器應確保 SetPhysicalSecureHeapRanges() 成功或失敗，並以不可分割的方式執行 (在完成前完全更新或復原)。
5	`is_mod_protected_range_available`	`bool`	如果為 true，則會實作 ModifySecureHeapPhysicalRange()。如果 is_mod_protected_range_available 為 false，則禁止呼叫 ModifySecureHeapPhysicalRange()。請勿嘗試呼叫 ModifySecureHeapPhysicalRange() 來偵測其可用性，因為這可能會導致 ZX_PANIC()。

SecureHeapRange

已淘汰：23 新增：7

序數	欄位	類型	說明
1	`physical_address`	`uint64`	必須至少與 heap_range_granularity 對齊。
2	`size_bytes`	`uint64`	必須至少與 heap_range_granularity 對齊。

SecureHeapsAndRanges

已淘汰：23 新增：7

序數	欄位	類型	說明
1	`heaps`	`vector<SecureHeapAndRanges>:32`

UNIONS

Node_IsAlternateFor_Result strict

序數	Variant	類型	說明
1	`response`	`Node_IsAlternateFor_Response`
2	`err`	`zx/Status`

SecureMem_AddSecureHeapPhysicalRange_Result strict

序數	Variant	類型	說明
1	`response`	`SecureMem_AddSecureHeapPhysicalRange_Response`
2	`err`	`zx/Status`

strict SecureMem_DeleteSecureHeapPhysicalRange_Result

序數	Variant	類型	說明
1	`response`	`SecureMem_DeleteSecureHeapPhysicalRange_Response`
2	`err`	`zx/Status`

SecureMem_GetPhysicalSecureHeapProperties_Result strict

序數	Variant	類型	說明
1	`response`	`SecureMem_GetPhysicalSecureHeapProperties_Response`
2	`err`	`zx/Status`

SecureMem_GetPhysicalSecureHeaps_Result strict

序數	Variant	類型	說明
1	`response`	`SecureMem_GetPhysicalSecureHeaps_Response`
2	`err`	`zx/Status`

SecureMem_ModifySecureHeapPhysicalRange_Result strict

序數	Variant	類型	說明
1	`response`	`SecureMem_ModifySecureHeapPhysicalRange_Response`
2	`err`	`zx/Status`

SecureMem_ZeroSubRange_Result strict