Fuchsia.sysmem

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

此連線有助於以非同步方式指示在邏輯 BufferCollection 已填入緩衝區時。

此外，伺服器關閉管道可指示用戶端，用戶端應盡快關閉從 BufferCollection 取得的所有 VMO 帳號。

此外，這個介面日後可能會允許以其他方式指定限制，還可能允許來回協商限制。

這個介面日後可能會允許每個 BufferCollection 超過 64 個 VMO 處理，但目前上限為 64 個。

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

部分啟動器可能會等待很短的持續時間，直到所有舊的邏輯 BufferCollection VMO 控制代碼關閉 (或直到縮短為止)，然後再分配新的 BufferCollection，才能協助控制實體記憶體片段化，並避免新舊集合的緩衝區分配生命週期重疊。集合可能夠大，因此有必要避免配置重疊。

AttachLifetimeTracking

AttachLifetimeTracking：

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

將事件配對端點附加至邏輯緩衝區集合，這樣當分配的緩衝區數量下降至「buffers_remaining」時，server_end 將會關閉。邏輯配置完成後，server_end 才會關閉。

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

此事件發出的生命週期信號包括已配置緩衝區的非同步清除作業，且除非 VMO 處理緩衝區的所有容器都關閉這些 VMO 處理，否則無法進行非同步清除作業。因此，用戶端在等待 ZX_EVENTPAIR_PEER_CLOSED 收到訊號之後，應小心不要被封鎖，尤其是使用邏輯緩衝區收集的任何參與者不信任或較不可靠的時。

buffers_remaining 參數等待所有緩衝區_remaining buffers 完全取消配置。當已知的緩衝區刻意關閉時，此做法非常實用，以便能繼續使用資料，例如即使影片串流使用受保護的輸出緩衝區，也能持續在 UI 中顯示最新的可用視訊畫面。這不在 BufferCollection 介面的範圍 (目前至少) 範圍內，無法確定在不關閉的情況下可保留多少緩衝區，但通常會落在 0 到 2 的範圍內。

這個機制旨在與提供類似 AttachLifetimeTracking() 機制的通訊協定相容，因為同一個事件的重複項目可傳送至多個 AttachLifetimeTracking()，並且在滿足所有生命週期內超過條件時發出信號 (ZX_EVENTPAIR_PEER_CLOSED)。

而且無法取消附加作業。關閉事件配對的用戶端並不會從待處理連接數量減去。

關閉用戶端並不會導致伺服器執行任何動作。如果伺服器完全監聽來自用戶端的事件，則只會用於偵錯記錄。

伺服器刻意不會「信任」用戶端傳送的任何位元。此機制刻意只使用無法提早觸發的 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 管道的用戶端的角度來看，符記的運作方式與其他符記一樣。用戶端可以視需要複製權杖，並將憑證傳送至不同的程序。請照常呼叫 BindSharedCollection()，將權杖轉換為 BufferCollection 管道。您應在該 BufferCollection 管道呼叫 SetConstraints()。

WaitForBuffersAllocations() 的成功結果表示新參與者的限制可以使用現有的緩衝區集合、已建立的 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

如果已分配或失敗的緩衝區收集，此方法會傳回與 waitForBuffersAllocations 相同的結果代碼；如果 WaitForBuffersAllocations 會封鎖，則會傳回 ZX_ERR_UNAVAILABLE。

要求

<EMPTY>

回應

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

關閉

在 BufferCollectionToken 管道上：

通常，參與者會將 BufferCollectionToken 轉換為 BufferCollection 檢視畫面，但參與者也可以自由使用 Close() 憑證 (然後立即或稍後關閉管道，回應伺服器結束其端)，避免造成邏輯緩衝區收集失敗。通常，意外的權杖管道關閉會導致邏輯緩衝區收集失敗 (特定情況是涉及 AttachToken() 或 SetDispensable() 的例外情況)。

在 BufferCollection 管道上：

根據預設，伺服器會失敗整個邏輯緩衝區收集，以處理 BufferCollection 的非預期的錯誤。其中一部分是加速關閉 VMO 控制代碼，以便在任何參與者失敗時收回記憶體。如果參與者想要徹底關閉 BufferCollection 檢視畫面，而不造成邏輯緩衝區收集失敗，參與者可以先傳送 Close()，再關閉 BufferCollection 管道的用戶端。如果這是最後一個 BufferCollection 檢視畫面，邏輯緩衝區集合仍會消失。Close() 可能會在 SetConstraints() 之前或之後發生。如果在 SetConstraints() 之前或之後，緩衝區集合則不需要此節點的限制即可分配。在 SetConstraints() 之後，即使沒有管道連線，系統仍會保留並匯總限制與任何後續的邏輯分配。

在 BufferCollectionTokenGroup 管道上：

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

如果 Close() 發生在 AllChildrenPresent() 之前，這個邏輯緩衝區收集仍會因 Close() 而失敗 (因為 sysmem 無法確定是否所有相關的子項都建立成功，所以會不清楚是否將所有相關的限制條件提供給 sysmem)。如果 Close() 在 AllChildrenPresent() 後出現，子項及其所有限制都會完整保留 (就像 BufferCollectionTokenGroup 管道保持開啟時一樣)，且關閉不會觸發或傳播失敗。

新增日期：9

要求

<EMPTY>

DeprecatedClose

新增日期：9

要求

<EMPTY>

DeprecatedSetDebugClientInfo

新增日期：9

要求

名稱	類型
`name`	`string[64]`
`id`	`uint64`

DeprecatedSetName

新增日期：9

要求

名稱	類型
`priority`	`uint32`
`name`	`string[64]`

DeprecatedSync

新增日期：9

要求

<EMPTY>

回應

<EMPTY>

GetAuxBuffers

已移除：HEAD 已淘汰：9 已新增：7

要求

<EMPTY>

回應

名稱	類型
`status`	`zx/Status`
`buffer_collection_info_aux_buffers`	`BufferCollectionInfo_2`

GetNodeRef

這會取得事件處理常式，可做為在任何節點上呼叫的 IsAlternativeFor() 參數。用戶端無法就此事件發出信號，因為這個帳號代碼只能用來證明用戶端已從這個節點取得此控制代碼。

由於這是 get 並非集合，因此在 GetNodeRef() 和 IsalternateFor() 的呼叫之間不需要 Sync()，即使兩次呼叫可能位於不同的管道。

另請參閱 IsAlternativeFor()。

新增日期：9

要求

<EMPTY>

回應

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

IsAlternateFor

這會檢查呼叫節點是否位於共同父項 BufferCollectionTokenGroup 的不同子項權杖的子樹狀結構中，與傳入的 node_ref。

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

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

node_ref 可以是重複的控制代碼；您不必在每次呼叫 IsalternateFor() 時呼叫 GetNodeRef()。

如果因權杖可能具有惡意/不受信任的提供者，而呼叫權杖根本不能為有效憑證，請先呼叫 VerifiedBufferCollectionToken()，如果 IsAlternativeFor() 呼叫不是真實權杖而未回應 (而不是真的與 sysmem 通訊)，則可能不會無限期地停止運作。另一種選擇是先使用這個符記呼叫 BindSharedCollection，這個權杖同樣會驗證權杖，同時將其轉換為 BufferCollection，然後呼叫 BufferCollection IsAlternativeFor()。

錯誤值：

ZX_ERR_NOT_FOUND 表示在與呼叫節點相同的邏輯緩衝區集合中，找不到 node_ref。在邏輯配置和同一個邏輯配置子樹狀結構中，本質上表示 node_ref 從未納入這個邏輯緩衝區集合，因為在邏輯配置之前，所有具備的 node_ref 至少會保持存在，包括已連接了 Close() 且關閉其管道的節點；如果是 ZX_ERR_NOT_FO，則該管道仍需要連接節點。在邏輯配置或不同的邏輯分配子樹狀結構後，則有其他可能的原因造成此錯誤。例如，以 AttachToken() 或 SetDispensable() 分隔的邏輯分配與此節點的邏輯分配不同的例子，可能會失敗其子樹狀結構刪除這些節點；或者，BufferCollectionTokenGroup 可能會存在，而選取與 node_ref 做為子樹狀結構不同的子樹狀結構，導致 node_ref 節點遭到刪除。只有在該節點沒有對應管道後，sysmem 才會保留節點。當使用 Close()，且節點的子樹狀結構尚未失敗時，Smem 才會保留節點。另一個這個錯誤的原因是，node_ref 是具有足夠權限的事件配對控制代碼，但實際上並非從 GetNodeRef() 取得的實際 node_ref。

ZX_ERR_INVALID_ARGS 表示呼叫端傳遞的 node_ref 並非事件配對控制代碼，或是對於實際的 node_ref 不具備所需權限。

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

成功時，is_alternate 的意義如下：

true - 呼叫節點與 node_ref 節點之間共用的第一個父項節點是 BufferCollectionTokenGroup。這表示呼叫的節點和 node_ref 節點「不」同時套用這兩項限制，而 sysmem 會選擇其中一個以上的限制，但不會兩者同時適用。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有一個子項子樹狀結構造成限制匯總。
false - 呼叫節點與 node_ref Node 之間共用的第一個父項節點不是 BufferCollectionTokenGroup。目前，這表示共用的第一個父項節點是 BufferCollectionToken 或 BufferCollection (不論未關閉 Close()ed 或 Close()ed)。這意味著，在涉及邏輯分配的任何父項 BufferCollectionTokenGroup 中選取了兩個節點時，呼叫的節點和 node_ref Node 可能在限制期間會同時套用這兩個節點的限制。在這個案例中，沒有任何 BufferCollectionTokenGroup 會直接防止兩個節點同時被選取及其限制被匯總。不過，即使為 false，如果其中一個節點有直接或兩個節點具有直接或間接的 Node-treeor 節點，則節點的間接父項 BufferCollectionTokenGroup 則排除了包含子樹狀結構或參照子樹狀結構的子樹狀結構或「都會」之外，系統仍然不會將這些節點納入考量。

新增日期：9

要求

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

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

SetConstraints

將 BufferCollectionConstraints 提供給邏輯 BufferCollection。

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

有時候，發起者只是想留意是否成功填入緩衝區成功/失敗情況的參與者，而失敗時則為 zx.Status。在這種情況下，has_constraints 可以是 false，系統會忽略 constraints。

系統不會將 VMO 控制代碼提供給傳送空值限制的用戶端，這可能會刻意用於不需要 VMO 處理的啟動器。沒有 VMO 控制代碼不會阻止啟動器調整緩衝區的哪些部分有效和類似的，但啟動者無法保留 VMO 控制代碼開啟，以防止邏輯 BufferCollection 遭到清除，無論啟動者的參與程度為何。

為了嘗試填入緩衝區，BufferCollection 用戶端管道的所有容器必須呼叫 SetConstraints()，系統才能嘗試分配緩衝區。

has_constraints 如果為 false，則有效為空值，系統會忽略 constraints。空值限制的傳送者不會在 BufferCollectionInfo 中獲得任何 VMO 控點，但仍可查看已分配的緩衝區數量，且仍可透過 buffer_index 參照緩衝區。

constraints 是緩衝區集合的限制。

要求

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

SetConstraintsAuxBuffers

已移除：HEAD 已淘汰：9 已新增：7

要求

名稱	類型
`constraints`	`BufferCollectionConstraintsAuxBuffers`

SetDebugClientInfo

啟用詳細記錄功能時，也會使用這個方法 (請參閱 SetVerboseLogging())，指出哪個用戶端先關閉頻道，導致子樹狀結構故障 (如果子樹狀結構的用途遭到超出，這可能很正常，但如果發生時間低於預期，用戶端專屬名稱有助於診斷失敗的首要來源，例如 sysmem 的觀點)。

根據預設 (除非透過這則訊息覆寫，或使用 Allocator.SetDebugClientInfo())，節點會在建立子項節點時，從父項節點複製資訊。雖然這樣可能更好，但最好讓每位參與者使用 Node.SetDebugClientInfo() 或 Allocator.SetDebugClientInfo()，讓資訊直接與目前的用戶端相關。此外，SetVerboseLogging() 也可用於釐清節點是否疑似含有從父項複製的資訊。

新增日期：9

要求

名稱	類型
`name`	`string[64]`
`id`	`uint64`

SetDebugTimeoutLogDeadline

如果所有用戶端在建立集合後只有 5 秒設定限制，Sysmem 就會記錄警告。用戶端可呼叫此方法，在列印記錄時變更。如果有多個用戶端設定期限，將無法指定哪個用戶端會生效。

新增日期：9

要求

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

SetName

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

新增日期：9

要求

名稱	類型
`priority`	`uint32`
`name`	`string[64]`

SetVerboseLogging

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

通常，Semem 在匯總失敗時只會列印一行申訴，且只會列出匯總失敗的具體原因，且幾乎不需使用背景資訊。雖然通常只要進行小幅變更，且系統在小幅變更之前已運作正常，通常就足以診斷問題，但這對首次使用新的緩衝區集合通常並不特別有幫助。特別是在較複雜的節點樹狀結構中，涉及 AttachToken()、SetDispensable()、BufferCollectionTokenGroup 節點和相關節點的子樹狀結構，詳細記錄可能有助於診斷樹狀結構的樣貌，以及為何邏輯配置失敗，或是樹狀結構或子樹狀結構較早失敗的原因。

如果僅在少量緩衝區集合中啟用，從效能觀點查看額外記錄的意圖是可接受的。如果您並未追蹤錯誤，我們不應傳送這則訊息。

如果有太多參與者保留詳細記錄功能，我們最終可能需要透過某些其他設定，允許整個系統的 sysmem 詳細記錄，以免記錄因這則訊息而過度濫發 Sysem 記錄。

某些節點可能會因為與節點相關聯的蓄意政策而產生 NOP，如果我們認為節點的信任度不足以讓節點開啟詳細記錄功能，這可能就會是 NOP。

新增日期：9

要求

<EMPTY>

同步

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

對非有效 sysmem 憑證的權杖呼叫 BufferCollectionToken.Sync() 可能會導致 Sync() 永久停止運作。請參閱 VerificationBufferCollectionToken() 方法，瞭解在一趟來回行程中，出現惡意/假 BufferCollectionToken 的風險。另一種方法是將權杖傳送至 BindSharedCollection()，此函式在與 BufferCollection 管道交換憑證時也會驗證憑證，接著便可使用 BufferCollection Sync()。

Sync() 之後，您可以放心將 token_request 的用戶端端傳送給其他參與者，只要對方知道伺服器將憑證傳送至 BindSharedCollection()，就可辨識出該符記。

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

另一個減緩方法是避免對權杖呼叫 Sync()，導致在原始權杖無效時，之後會發生 BufferCollection.Sync() 可能失敗的情況。比起效能的觀點，此選項更適合，但用戶端程式碼必須延遲傳送來自這個憑證的重複憑證，直到用戶端程式碼將複製的權杖轉換成 BufferCollection 並收到 BufferCollection.Sync() 的成功回應為止。

在可能的情況下，建議您改用 BufferCollection.Sync() (請見上文)。當 BufferCollection.Sync() 無法使用時，呼叫端必須已經知道此憑證有效，或者 BufferCollectionToken.Sync() 可能會永久停止運作。如果要先檢查符記是否有效 (是否為有效)，請參閱 VerifiedBufferCollectionToken()。

新增日期：9

要求

<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/Status`
`buffer_collection_info`	`BufferCollectionInfo_2`

BufferCollectionToken

BufferCollectionToken 不是 BufferCollection，而是用來在分配 BufferCollection 之前識別潛在的共用緩衝區。

我們使用管道做為 BufferCollectionToken，而不是單一事件組合 (配對)，因為這樣我們能夠偵測例如參與者在建立期間發生的錯誤條件。

關閉

在 BufferCollectionToken 管道上：

在 BufferCollection 管道上：

在 BufferCollectionTokenGroup 管道上：

新增日期：9

要求

<EMPTY>

CreateBufferCollectionTokenGroup

大部分的 sysmem 用戶端和許多參與者通常不需要關注這則訊息或 BufferCollectionTokenGroup(s)。

BufferCollectionTokenGroup 是用來在 N 個子符記之間建立 N OR 的一個。匯總期間未選取的子項權杖會失敗 (關閉)，潛在參與者應在 BufferCollection 管道用戶端端點看到 PEER_CLOSED 時注意到這個符記，允許參與者清除未結束的推測使用情形 (類似一般 BufferCollection 伺服器在邏輯緩衝區收集失敗時結束)。

查看通訊協定 BufferCollectionTokenGroup 的註解。

凡是要套用到整個群組的權利_attenuation_mask 或 AttachToken()/SetDispensable()，皆可使用符記做為群組的直接父項來達成。

group_request - sysmem 提供的 BufferCollectionTokenGroup 管道的伺服器端。

新增日期：9

要求

名稱	類型
`group_request`	`server_end<BufferCollectionTokenGroup>`

DeprecatedClose

新增日期：9

要求

<EMPTY>

DeprecatedSetDebugClientInfo

新增日期：9

要求

名稱	類型
`name`	`string[64]`
`id`	`uint64`

DeprecatedSetDebugTimeoutLogDeadline

新增日期：9

要求

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

DeprecatedSetName

新增日期：9

要求

名稱	類型
`priority`	`uint32`
`name`	`string[64]`

DeprecatedSync

新增日期：9

要求

<EMPTY>

回應

<EMPTY>

複製

此方法可在建立共用 BufferCollection 之前新增參與者。只有在效能敏感的情況下，才需要使用 DuplicateSync，這是不適合用來等待系統回應每個重複項目的一部分的 sysmem。

傳送一或多個 Duplicate() 訊息、將已建立的權杖傳送給其他參與者 (或其他配置器管道) 之前，用戶端應傳送 Sync() 並等待其回應。Sync() 呼叫可在權杖上進行，或是在將這個權杖傳送至 BindSharedCollection() 而取得的 BufferCollection 上。您都會確保伺服器事先知道透過 Duplicate() 建立的憑證，之後其他參與者透過獨立的 Allocator 管道將權杖傳送至伺服器。

所有符記都必須透過 BindSharedCollection() 或 Close() 啟用，才能成功建立 BufferCollection。

當用戶端呼叫 BindSharedCollection() 開啟 BufferCollectionToken 時，伺服器會先處理所有 Duplicate() 訊息後，關閉 BufferCollectionToken。這可讓用戶端對 Duplicate() 產生立即使用 BindSharedCollection 的 BufferCollectionToken，然後才將 token_request 的用戶端端轉移至其他參與者。在考慮此 BufferCollectionToken 完全關閉之前，伺服器會發現 token_request 確實存在。

在這個遮罩中，rights_attenuation_mask 的權利位元在 token_request 的用戶端端可取得的緩衝區 VMO 權利中將不存在。讓發起人或中介者能提及參與者可用的權利。這不允許參與者取得參與者尚未擁有的權限。值 ZX_RIGHT_SAME_RIGHTS 可用來指定不套用注意力。

下列 Rights_attenuation_mask 的值將不會生效：

ZX_RIGHT_SAME_RIGHTS (建議選項)
0xFFFFFFFF (在計算注意力面遮罩時相當合理)
0 (已淘汰 - 請勿使用 0 - 「ERROR」會列入記錄)

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

要求

名稱	類型
`rights_attenuation_mask`	`uint32`
`token_request`	`server_end<BufferCollectionToken>`

DuplicateSync

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

如果因權杖的潛在/不受信任提供者，而呼叫權杖根本不能是有效憑證，請考慮先使用 VerifiedBufferCollectionToken()，而若 DuplicateSync() 因呼叫權杖不是實際權杖而做出回應，則可能無限期暫時停止回應。

相較於 Duplicate()，呼叫此方法後不需要 Sync() (請參閱「通訊協定節點」)。

所有符記都必須透過 BindSharedCollection() 或 Close() 啟用，才能成功建立 BufferCollection。

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

要求

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

回應

名稱	類型
`tokens`	`vector<BufferCollectionToken>[64]`

GetNodeRef

由於這是 get 並非集合，因此在 GetNodeRef() 和 IsalternateFor() 的呼叫之間不需要 Sync()，即使兩次呼叫可能位於不同的管道。

另請參閱 IsAlternativeFor()。

新增日期：9

要求

<EMPTY>

回應

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

IsAlternateFor

這會檢查呼叫節點是否位於共同父項 BufferCollectionTokenGroup 的不同子項權杖的子樹狀結構中，與傳入的 node_ref。

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

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

node_ref 可以是重複的控制代碼；您不必在每次呼叫 IsalternateFor() 時呼叫 GetNodeRef()。

錯誤值：

ZX_ERR_INVALID_ARGS 表示呼叫端傳遞的 node_ref 並非事件配對控制代碼，或是對於實際的 node_ref 不具備所需權限。

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

成功時，is_alternate 的意義如下：

true - 呼叫節點與 node_ref 節點之間共用的第一個父項節點是 BufferCollectionTokenGroup。這表示呼叫的節點和 node_ref 節點「不」同時套用這兩項限制，而 sysmem 會選擇其中一個以上的限制，但不會兩者同時適用。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有一個子項子樹狀結構造成限制匯總。
false - 呼叫節點與 node_ref Node 之間共用的第一個父項節點不是 BufferCollectionTokenGroup。目前，這表示共用的第一個父項節點是 BufferCollectionToken 或 BufferCollection (不論未關閉 Close()ed 或 Close()ed)。這意味著，在涉及邏輯分配的任何父項 BufferCollectionTokenGroup 中選取了兩個節點時，呼叫的節點和 node_ref Node 可能在限制期間會同時套用這兩個節點的限制。在這個案例中，沒有任何 BufferCollectionTokenGroup 會直接防止兩個節點同時被選取及其限制被匯總。不過，即使為 false，如果其中一個節點有直接或兩個節點具有直接或間接的 Node-treeor 節點，則節點的間接父項 BufferCollectionTokenGroup 則排除了包含子樹狀結構或參照子樹狀結構的子樹狀結構或「都會」之外，系統仍然不會將這些節點納入考量。

新增日期：9

要求

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

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

SetDebugClientInfo

新增日期：9

要求

名稱	類型
`name`	`string[64]`
`id`	`uint64`

SetDebugTimeoutLogDeadline

新增日期：9

要求

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

SetDispensable

系統按照邏輯分配緩衝區後，發行的權杖可能會失敗，而不會導致父項 (如果有的話) 失敗。

可支付權杖會在邏輯緩衝區分配前，參與限制匯總及其父項。如果在邏輯分配緩衝區前，分得權杖仍失敗，則錯誤會傳播至可供應權杖的父項。

系統按照邏輯分配緩衝區後，可供應權杖 (或任何可供應權杖的子項) 失敗，不會傳播至可支付權杖的父項。失敗作業會從可供應權杖的一般子項傳播至可分配權杖。如果附加了子項，或者如果子項可供應，而在邏輯配置後發生失敗，則子項失敗就無法聯繫其父項。

如果參與者需要提供限制，但系統分配了緩衝區，可以使用可用權杖，但參與者可能會失敗，而不會從父項視角發生緩衝區收集作業。

相較之下，AttachToken() 可以用來建立權杖，該權杖不會參與與父項的限制匯總，且如果隨時都失敗，就不會傳播至父項，且如果延遲提供限制條件，並不會導致父項完成緩衝區分配。

如果用戶端使用這則訊息，由於用戶端包含 SetDispensable() 且提供給其他程序的任何 BufferCollectionToken 或 BufferCollection 發生問題，因此用戶端不應仰賴用戶端自己的 BufferCollectionToken 或 BufferCollection 管道來關閉伺服器。因此，客戶應格外小心，留意其他程序因其他程序失敗。

雖然對 BufferCollectionTokenGroup 的直接子項可以採用 SetDispensable() 有用 (而且可能很有用)，但在之後無法使用 AttachToken() 將原為群組直接子項的失敗憑證取代為新權杖 (因為一個群組沒有 AttachToken())。如要在這種情況下啟用 AttachToken() 取代功能，請建立另一個不可支付的權杖 (節點)，這是群組的直接子項，並將現有可支付權杖設為額外權杖 (節點) 的子項。如此一來，做為群組的直接子項額外權杖 (節點) 就會擁有 BufferCollection.AttachToken()，用於取代失敗的可發放憑證。

對已供應的權杖上的 SetDispensable() 是冪等的。

要求

<EMPTY>

SetName

新增日期：9

要求

名稱	類型
`priority`	`uint32`
`name`	`string[64]`

SetVerboseLogging

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

如果僅在少量緩衝區集合中啟用，從效能觀點查看額外記錄的意圖是可接受的。如果您並未追蹤錯誤，我們不應傳送這則訊息。

某些節點可能會因為與節點相關聯的蓄意政策而產生 NOP，如果我們認為節點的信任度不足以讓節點開啟詳細記錄功能，這可能就會是 NOP。

新增日期：9

要求

<EMPTY>

同步

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

Sync() 之後，您可以放心將 token_request 的用戶端端傳送給其他參與者，只要對方知道伺服器將憑證傳送至 BindSharedCollection()，就可辨識出該符記。

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

新增日期：9

要求

<EMPTY>

回應

<EMPTY>

BufferCollectionTokenGroup

系統保證 Smem 實作會與邏輯/概念模型保持一致，如下所示：

像往常一樣，邏輯分配會考量未傳輸 AttachToken() 根憑證的根層級和所有連至根層級之子樹狀結構的子樹狀結構，以及所有與該子樹狀結構連線且未傳遞另一個 AttachToken() 的節點。這稱為邏輯配置的已修剪子樹狀結構，或為短時間遭到截斷的子樹狀結構。

在限制匯總期間，每個 BufferCollectionTokenGroup 都會在其子項中選取單一子符記。其餘子項看起來會失敗邏輯分配，而所選子項可能會成功。

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

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

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

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

嘗試匯總不對等的選項組合，會以這種方式繼續匯總，直到整體邏輯配置失敗時，所有匯總嘗試失敗，或 (b) 直到嘗試匯總成功為止，此時，系統會嘗試執行緩衝區分配 (如有需要)。如果依據第一次成功匯總失敗的緩衝區分配失敗，整體邏輯分配就會失敗 (但沒有緩衝區分配重試 / 重新嘗試)。如果緩衝區分配成功 (或不需要)，邏輯分配就會成功。

如果這種優先排序機制無法對使用 sysmem 的應用方式合理運作，請與 sysmem 使用者聯絡，討論或許可以新增方法來達成此需求。

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

在可行情況下，最好在單一 BufferCollectionConstraint 中使用多個 ImageFormatConstraints (當參與者只需要表達使用多個 PixelFormat 的能力時，並且選擇所有參與者支援的 PixelFormat 即可)。

與 BufferCollectionToken 和 BufferCollection 類似，關閉 BufferCollectionTokenGroup 管道時若沒有先傳送 Close()，就會導致邏輯緩衝區收集失敗 (如果使用 SetDispensable() 或 AttachToken()，而 BufferCollectionTokenGroup 是子樹狀結構底下的子樹狀結構的一部分，該節點不會傳播至其父項的故障)。

新增日期：9

AllChildrenPresent

AllChildrenPresent()

建立所有子項後，用戶端必須呼叫 AllChildrenPresent() 以告知 sysmem 不會再建立任何子項，讓 sysmem 知道何時可以啟動匯總限制。

如果已傳送 Close()，則應在 AllChildrenPresent() 之後傳送，否則即使群組失敗，且仍會觸發無法傳播至群組的父項。

要求

<EMPTY>

關閉

在 BufferCollectionToken 管道上：

在 BufferCollection 管道上：

在 BufferCollectionTokenGroup 管道上：

新增日期：9

要求

<EMPTY>

CreateChild

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

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

Rights_attenuation_mask - 如果為 ZX_RIGHT_SAME_RIGHTS，則已建立的憑證可讓持有者取得與緩衝區 (群組) 父項權杖相同的權利。

要求

名稱	類型
`payload`	`BufferCollectionTokenGroupCreateChildRequest`

CreateChildrenSync

以同步方式一次建立一或多個子權杖。與 CreateChild() 不同，在將傳回的權杖的用戶端結尾傳送至 BindSharedCollection() 前，不需要完成 Sync()。

Rights_attentuation_mask 的大小決定了已建立的子符記數量。

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

依據所有子符記，成功匯總會在所有已建立的子項中選擇一個子項 (也就是在所有可能多次呼叫 CreateChild() 和 CreateChildrenSync() 的子項中)。

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

要求

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

回應

名稱	類型
`tokens`	`vector<BufferCollectionToken>[64]`

GetNodeRef

由於這是 get 並非集合，因此在 GetNodeRef() 和 IsalternateFor() 的呼叫之間不需要 Sync()，即使兩次呼叫可能位於不同的管道。

另請參閱 IsAlternativeFor()。

新增日期：9

要求

<EMPTY>

回應

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

IsAlternateFor

這會檢查呼叫節點是否位於共同父項 BufferCollectionTokenGroup 的不同子項權杖的子樹狀結構中，與傳入的 node_ref。

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

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

node_ref 可以是重複的控制代碼；您不必在每次呼叫 IsalternateFor() 時呼叫 GetNodeRef()。

錯誤值：

ZX_ERR_INVALID_ARGS 表示呼叫端傳遞的 node_ref 並非事件配對控制代碼，或是對於實際的 node_ref 不具備所需權限。

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

成功時，is_alternate 的意義如下：

true - 呼叫節點與 node_ref 節點之間共用的第一個父項節點是 BufferCollectionTokenGroup。這表示呼叫的節點和 node_ref 節點「不」同時套用這兩項限制，而 sysmem 會選擇其中一個以上的限制，但不會兩者同時適用。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有一個子項子樹狀結構造成限制匯總。
false - 呼叫節點與 node_ref Node 之間共用的第一個父項節點不是 BufferCollectionTokenGroup。目前，這表示共用的第一個父項節點是 BufferCollectionToken 或 BufferCollection (不論未關閉 Close()ed 或 Close()ed)。這意味著，在涉及邏輯分配的任何父項 BufferCollectionTokenGroup 中選取了兩個節點時，呼叫的節點和 node_ref Node 可能在限制期間會同時套用這兩個節點的限制。在這個案例中，沒有任何 BufferCollectionTokenGroup 會直接防止兩個節點同時被選取及其限制被匯總。不過，即使為 false，如果其中一個節點有直接或兩個節點具有直接或間接的 Node-treeor 節點，則節點的間接父項 BufferCollectionTokenGroup 則排除了包含子樹狀結構或參照子樹狀結構的子樹狀結構或「都會」之外，系統仍然不會將這些節點納入考量。

新增日期：9

要求

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

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

SetDebugClientInfo

新增日期：9

要求

名稱	類型
`name`	`string[64]`
`id`	`uint64`

SetDebugTimeoutLogDeadline

新增日期：9

要求

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

SetName

新增日期：9

要求

名稱	類型
`priority`	`uint32`
`name`	`string[64]`

SetVerboseLogging

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

如果僅在少量緩衝區集合中啟用，從效能觀點查看額外記錄的意圖是可接受的。如果您並未追蹤錯誤，我們不應傳送這則訊息。

某些節點可能會因為與節點相關聯的蓄意政策而產生 NOP，如果我們認為節點的信任度不足以讓節點開啟詳細記錄功能，這可能就會是 NOP。

新增日期：9

要求

<EMPTY>

同步

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

Sync() 之後，您可以放心將 token_request 的用戶端端傳送給其他參與者，只要對方知道伺服器將憑證傳送至 BindSharedCollection()，就可辨識出該符記。

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

新增日期：9

要求

<EMPTY>

回應

<EMPTY>

DriverConnector

定義於 fuchsia.sysmem/driver_connector.fidl

將具有這個介面的管道建立為驅動程式庫後 (通常如此)，這個介面就能以非同步方式，傳送驅動程式庫提供的分配器管道端伺服器端。

目前，sysmem 驅動程式庫只會透過一般 devhost FIDL 分派程式碼直接提供的 FIDL 介面是此介面。其他 sysmem 介面主要是由不同的分派程式碼提供，因為我們希望能夠將伺服器管道傳送給驅動程式庫，以非同步的方式建立管道，這樣無需來回切換管道，也不必將管道當做檔案描述元管理。

https://fxbug.dev/42108063 追蹤的第二大原因是，目前的 devhost 分派程式碼不允許非同步處理要求，因此我們至少想讓 BufferCollection 介面正確運作，因為該介面在 devhost 出現其他參與者限制之前未能完成的要求。

已移除：HEAD 已淘汰：9 已新增：7

連線

這則單向訊息會透過配置器管道的伺服器端傳送。

allocator_request 將由 sysmem 驅動程式提供 (或管道將關閉)。

要求

名稱	類型
`allocator_request`	`server_end<Allocator>`

SetAuxServiceDirectory

要求

名稱	類型
`service_directory`	`fuchsia.io/Directory`

節點

新增日期：9

關閉

在 BufferCollectionToken 管道上：

在 BufferCollection 管道上：

在 BufferCollectionTokenGroup 管道上：

新增日期：9

要求

<EMPTY>

GetNodeRef

由於這是 get 並非集合，因此在 GetNodeRef() 和 IsalternateFor() 的呼叫之間不需要 Sync()，即使兩次呼叫可能位於不同的管道。

另請參閱 IsAlternativeFor()。

新增日期：9

要求

<EMPTY>

回應

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

IsAlternateFor

這會檢查呼叫節點是否位於共同父項 BufferCollectionTokenGroup 的不同子項權杖的子樹狀結構中，與傳入的 node_ref。

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

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

node_ref 可以是重複的控制代碼；您不必在每次呼叫 IsalternateFor() 時呼叫 GetNodeRef()。

錯誤值：

ZX_ERR_INVALID_ARGS 表示呼叫端傳遞的 node_ref 並非事件配對控制代碼，或是對於實際的 node_ref 不具備所需權限。

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

成功時，is_alternate 的意義如下：

true - 呼叫節點與 node_ref 節點之間共用的第一個父項節點是 BufferCollectionTokenGroup。這表示呼叫的節點和 node_ref 節點「不」同時套用這兩項限制，而 sysmem 會選擇其中一個以上的限制，但不會兩者同時適用。這是因為在邏輯分配期間，系統只會選取 BufferCollectionTokenGroup 的一個子項，且只有一個子項子樹狀結構造成限制匯總。
false - 呼叫節點與 node_ref Node 之間共用的第一個父項節點不是 BufferCollectionTokenGroup。目前，這表示共用的第一個父項節點是 BufferCollectionToken 或 BufferCollection (不論未關閉 Close()ed 或 Close()ed)。這意味著，在涉及邏輯分配的任何父項 BufferCollectionTokenGroup 中選取了兩個節點時，呼叫的節點和 node_ref Node 可能在限制期間會同時套用這兩個節點的限制。在這個案例中，沒有任何 BufferCollectionTokenGroup 會直接防止兩個節點同時被選取及其限制被匯總。不過，即使為 false，如果其中一個節點有直接或兩個節點具有直接或間接的 Node-treeor 節點，則節點的間接父項 BufferCollectionTokenGroup 則排除了包含子樹狀結構或參照子樹狀結構的子樹狀結構或「都會」之外，系統仍然不會將這些節點納入考量。

新增日期：9

要求

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

回應

名稱	類型
`payload`	`Node_IsAlternateFor_Result`

SetDebugClientInfo

新增日期：9

要求

名稱	類型
`name`	`string[64]`
`id`	`uint64`

SetDebugTimeoutLogDeadline

新增日期：9

要求

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

SetName

新增日期：9

要求

名稱	類型
`priority`	`uint32`
`name`	`string[64]`

SetVerboseLogging

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

如果僅在少量緩衝區集合中啟用，從效能觀點查看額外記錄的意圖是可接受的。如果您並未追蹤錯誤，我們不應傳送這則訊息。

某些節點可能會因為與節點相關聯的蓄意政策而產生 NOP，如果我們認為節點的信任度不足以讓節點開啟詳細記錄功能，這可能就會是 NOP。

新增日期：9

要求

<EMPTY>

同步

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

Sync() 之後，您可以放心將 token_request 的用戶端端傳送給其他參與者，只要對方知道伺服器將憑證傳送至 BindSharedCollection()，就可辨識出該符記。

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

新增日期：9

要求

<EMPTY>

回應

<EMPTY>

SecureMem

SecureMem

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

TEE - 信任的執行環境。

REE - 豐富的執行環境。

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

目前，動態配置的安全堆積是透過 sysmem 設定，因為會在啟動期間很早啟動，並且可以成功保留連續的實體記憶體。目前，由於管道是從系統啟動載入程式移至 TEE，因此固定位置安全堆積是透過 TEE 設定。不過，這個通訊協定會刻意設定哪些堆積會經過動態配置，哪些是固定位置的，而刻意設定的堆積並不在乎。

AddSecureHeapPhysicalRange

這項從 sysmem 到 Securemem 驅動程式庫的要求會傳遞要新增的實體範圍，適用於透過 sysmem 設定實體範圍的堆積。

只有 sysmem 可以呼叫此方法，因為只有 sysmem 是透過 RegisterSecureMem() 來傳遞提供此通訊協定的 FIDL 管道用戶端端。Securemem 驅動程式是這個通訊協定的伺服器端。

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

失敗時，Securemem 驅動程式庫必須確保未建立受保護的範圍。

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

如果 dynamic_protection_ranges 為 true，則只要目前的範圍數量永不超過 max_protection_range_count，Smem 就可能會多次呼叫該範圍。

呼叫端不得嘗試新增與現有範圍相符的範圍。只要沒有兩個範圍完全相符，新增的範圍就能彼此重疊。

錯誤：

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

要求

名稱	類型
`heap_range`	`SecureHeapAndRange`

回應

名稱	類型
`payload`	`SecureMem_AddSecureHeapPhysicalRange_Result`

DeleteSecureHeapPhysicalRange

這項從 sysmem 到 Securemem 驅動程式庫的要求會傳遞要刪除的實體範圍，供透過 Smem 設定實體範圍的堆積。

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

失敗時，Safemem 驅動程式必須確保受保護的範圍未遭到刪除。

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

如果 dynamic_protection_ranges 為 true，sysmem 可以在呼叫時存在的不同範圍中重複呼叫此方法。

如果刪除的範圍中有任何部分不在其他保護範圍的涵蓋範圍內，則對整個範圍的任何進行中 DMA 可能會中斷 / 失敗，且可能破壞整個系統 (視裝置詳細資料而定)。因此，除非呼叫端具有其他有效範圍，且範圍涵蓋要刪除的範圍的每個區塊，否則呼叫端必須確保不會發生任何正在刪除的範圍部分進行中的指定行銷區域。持續進行的 DMA 與刪除範圍以外的區塊一律不會受到刪除作業影響。

錯誤：

ZX_ERR_BAD_STATE - 在 !dynamic_protection_ranges 時呼叫。
ZX_ERR_INVALID_ARGS - 非預期的堆積，或是不符合 Protect_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 的使用範圍，則以堆積的整個實體範圍來表示。在完成這項要求前，系統會刪除所有臨時硬體保護範圍。

新增日期：9

要求

名稱	類型
`entire_heap`	`SecureHeapAndRange`

回應

名稱	類型
`payload`	`SecureMem_GetPhysicalSecureHeapProperties_Result`

GetPhysicalSecureHeaps

取得透過 TEE 設定實體範圍的任何安全堆積的實際地址和長度。

目前，這些是固定的實際地址和長度，並透過 TEE 填入位置資訊。

在沒有需要特別設定或拆解任何 VMO 時，建議您優先使用 RegisterHeap()。

在安全系統驅動程式成功回應這項要求前，實體範圍必須受到 TEE 保護/保護。

Sysmem 只能呼叫一次。傳回零堆積並不會造成失敗。

錯誤：

ZX_ERR_BAD_STATE - 多次呼叫。
ZX_ERR_INTERNAL - 一般內部錯誤 (例如與 TEE 通訊時不會產生 zx_status_t 錯誤)。
其他錯誤可能存在，例如通訊失敗或伺服器傳播 zx_status_t 失敗

要求

<EMPTY>

回應

名稱	類型
`payload`	`SecureMem_GetPhysicalSecureHeaps_Result`

ModifySecureHeapPhysicalRange

從 sysmem 到 Securemem 驅動程式庫的要求，會傳遞實際範圍以修改，並傳遞透過 sysmem 設定實體範圍的堆積，以及其新的基礎和長度。

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

失敗時，Securemem 驅動程式庫必須確保範圍未遭到變更。

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

如果 dynamic_protection_ranges 為 true，sysmem 可以在呼叫時存在的不同範圍中重複呼叫此方法。

範圍只能擇一修改，不得同時修改兩者。如果範圍縮小，且未涵蓋的區塊未納入其他有效範圍，則任何正在傳入的 DMA 可能會中斷整個系統 (即公車鎖定或類似範圍)，因此呼叫端必須確保所有指定行銷區域不會遭到干擾範圍擴大，除非這些修改範圍未涵蓋其他正在發生的指定範圍，除非這些修改範圍未涵蓋其他正在發生的指定範圍，

如果將範圍修改為 <= 0，系統會刪除該範圍。

錯誤：

ZX_ERR_BAD_STATE - 在 !dynamic_protection_ranges 時呼叫。
ZX_ERR_INVALID_ARGS - 非預期的堆積、舊範圍或新範圍不符合 Protect_range_granularity，或是舊範圍與 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 設定的堆積範圍 (或涵蓋更多範圍) 且其設定會透過 GetSecure() 傳輸至 sys Secure 的整個實體範圍。

此要求不會影響持續進行的 DMA。

要求

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

回應

名稱	類型
`payload`	`SecureMem_ZeroSubRange_Result`

結構化

BufferCollectionConstraints

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

欄位	類型	說明	預設
`usage`	`BufferUsage`	該使用僅做為提示，協助 sysmem 在有多個相容的選項時，選擇最合適的 PixelFormat 或類似方式。匯總 BufferCollectionConstraints 時，這些值以位元表示或 OR。除非整個 BufferCollectionConstraints 於邏輯上為空值，否則必須指定至少一個用量位元。	無預設
`min_buffer_count_for_camping`	`uint32`	每位參與者可以同時保留給自己非短暫使用的緩衝數量。舉例來說，影片解碼器會指定 (至少) 參照影格數量上限 + 1 個影格目前已解碼。參與者不得長時間觀看超過此處指定的緩衝時間 (除非是短暫的)，否則處理程序可能會卡住。匯總 BufferCollectionConstraint 時，系統會加入這些值。在測試情境中，如果露營的緩衝區數量超過這個上限，則如果持續時間過長，系統可能會將其標記為失敗。在測試情境中，系統可能無法為參與者提供超過並行緩衝區數量。	無預設
`min_buffer_count_for_dedicated_slack`	`uint32`	每個參與者為簡化原因而需要的緩衝區數量下限，藉此改善處理重疊情形 / 提升效能。匯總 BufferCollectionConstraint 時，系統會加入這些值。參與者通常應在此指定 0 或 1 - 如果 min_buffer_count_for_camping 已足以讓參與者的忙碌時間在參與者稍晚 100% 的情況下保持忙碌，通常 0 即為適當；而 1 則適合因於營收區間而較需要的額外緩衝區，而 1 則適合。在測試情境中，這個欄位可能強制設為 0，所以所有參與者應該都能繼續運作，不會卡住。如果正向進度原因需要緩衝區，則該緩衝區應計入 min_buffer_count_for_camping。	無預設
`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。	無預設
`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 緩衝區的圖片，其圖片格式參數的選用限制。包括像素格式和圖片版面配置。這些限制是以像素格式為準，因此允許使用多個限制。清單中的項目像素格式不得重複。匯總時，系統只會保留由非零 image_format_constraints_count (和非空值) BufferCollectionConstraints 的所有參與者指定的像素格式。	無預設
`image_format_constraints`	`[32]`		無預設

BufferCollectionConstraintsAuxBuffers

已移除：HEAD 已淘汰：9 已新增：7

欄位類型說明預設

need_clear_aux_buffers_for_secure

bool

如果為 true，則只有在所有具有 BufferMemoryConstraints 的參與者指定 allow_clear_aux_buffers_for_secure 時，才能選取安全堆積。如果「需要」為 true，「allow」也必須是 true。

如果設為 False，參與者仍可正常運作，即使使用安全記憶體 (視支援的堆積而定)，不需要清除 Aaux 緩衝區。

無預設

allow_clear_aux_buffers_for_secure

bool

如果為 true，參與者會根據參與者的角色需求，使用明確的 Aaux 緩衝區。如果參與者是生產端，參與者製作者會將明確的 aux 緩衝區填入清楚 (未加密、未受 DRM 保護) 的位元組，並在受保護的位元組中填入不會模擬啟動碼的資料，例如 0xFF。

如果參與者從未傳送 BufferCollectionConstraintsAuxBuffers，則如果參與者指定只能讀取的使用情形，則「allow」為 true。

如果參與者未指定寫入用量或設為 false，如有任何參與者指定 need_clear_aux_buffers_for_secure true，緩衝區收集功能就無法分配。

無預設

BufferCollectionInfo 資源

定義於 fuchsia.sysmem/collections_Deprecatedd.fidl

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

欄位	類型	說明	預設
`buffer_count`	`uint32`	集合中的緩衝區數量。	無預設
`format`	`BufferFormat`	說明如何表示緩衝區內容的表示方式。集合中的所有緩衝區格式都相同。	無預設
`vmos`	`vmo[64]`	VMO 會處理集合中的每個緩衝區。只有在 VMO 支援緩衝區時，VMO 才會出現。如果存在，則 `buffer_count` 之後的所有 VMO 都是無效的控制代碼。所有緩衝區 VMO 控制代碼的大小和存取權相同。VMO 存取權取決於用戶端在分配緩衝區集合時指定的用量。例如，表示唯讀用法的用戶端會收到沒有寫入權限的 VMO。	無預設
`vmo_size`	`uint64`	提供的每個 VMO 大小。只有在 VMO 支援緩衝區時，才會出現這個屬性。	0

BufferCollectionInfo_2 資源

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

欄位類型說明預設

buffer_count

uint32

緩衝區總數。

無預設

settings

SingleBufferSettings

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

無預設

buffers

[64]

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

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

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

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

無預設

BufferFormat

定義於 fuchsia.sysmem/formats_Deprecatedd.fidl

說明如何表示緩衝區內容的表示方式。每種類型的緩衝區會以各自的資料表描述。

欄位	類型	說明	預設
`tag`	`uint32`	由於這個結構過去是單一成員聯集，因此我們保留標記，以避免任何傳輸格式變更。標記必須設為 `0`，其他值皆正確。	0
`image`	`ImageFormat`		無預設

BufferMemoryConstraints

欄位	類型	說明	預設
`min_size_bytes`	`uint32`		0
`max_size_bytes`	`uint32`	系統會將 0 視為 0xFFFFFFFF。	4294967295
`physically_contiguous_required`	`bool`		false
`secure_required`	`bool`	如果為 true，至少有一位參與者需要安全記憶體。匯總 BufferCollectionConstraint 時，這些值為布林值，或	false
`ram_domain_supported`	`bool`	根據預設，參與者必須確保 CPU 可以在不快取作業的情況下，在緩衝區中讀取或寫入資料。如果支援使用 RAM 網域，就必須在 RAM 中提供資料 (CPU 快取狀態，以免 RAM 資料因髒亂的 CPU 快取行將不正確的資料寫入 RAM 中)，且使用 CPU 的取用端必須在讀取之前使 CPU 快取失效 (生產端不保證「清除」快取行已過時)	false
`cpu_domain_supported`	`bool`		true
`inaccessible_domain_supported`	`bool`		false
`heap_permitted_count`	`uint32`	選用的堆積限制。如果參與者不在乎要分配哪些堆積記憶體，就應將這個欄位保留 0。	無預設
`heap_permitted`	`[32]`		無預設

BufferMemorySettings

欄位	類型	說明	預設
`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_Deprecatedd.fidl

說明圖片的表示方式。

欄位	類型	說明	預設
`width`	`uint32`	列寬度 (以像素為單位)。	無預設
`height`	`uint32`	列數。	無預設
`layers`	`uint32`	多圖層圖片中的圖層數量。如未指定，預設值為 1。	1
`pixel_format`	`PixelFormat`	像素格式。	無預設
`color_space`	`ColorSpace`	色域。	無預設
`planes`	`[4]`		無預設

ImageFormatConstraints

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

欄位	類型	說明	預設
`pixel_format`	`PixelFormat`	適用以下限制條件的 PixelFormat。參與者可能有多個支援的 PixelFormat，在這種情況下，參與者可以使用 ImageFormatConstraints 清單，並依照 PixelFormat 顯示項目。因為 ImageFormatConstraints 的其他欄位會因 PixelFormat 而不同而少見，例如線性格式可支援小於定格格式的線性格式。	無預設
`color_spaces_count`	`uint32`	空白是錯誤。多餘的項目則視為錯誤。任意順序並非錯誤。	無預設
`color_space`	`[32]`		無預設
`min_coded_width`	`uint32`	允許的最小寬度 (以像素為單位)。舉例來說，影片解碼器參與者可將這個欄位設為串流可能會指定的最小 coded_width。相對來說，required_min_coded_width 會設為串流指定的目前 Code_width。儘管 min_coded_width 會藉由獲取最大值來匯總，而 required_min_coded_width 則會大量匯總。另請參閱 required_min_coded_width 。	無預設
`max_coded_width`	`uint32`	寬度上限 (以像素為單位)。舉例來說，View 可能會將這個欄位 (直接或透過子參與者) 設為可合併的最大寬度。系統會將 0 視為 0xFFFFFFFF。	無預設
`min_coded_height`	`uint32`	高度下限 (以像素為單位)。舉例來說，影片解碼器參與者可將這個欄位設為串流指定的 coded_height。	無預設
`max_coded_height`	`uint32`	高度上限 (以像素為單位)。舉例來說，View 可能會將這個欄位 (直接或透過子參與者) 設為可合併的最大高度。系統會將 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`	Code_width % width_divisor 必須是 0。系統會將 0 視為 1。	1
`coded_height_divisor`	`uint32`	code_height % height_divisor 必須為 0。系統會將 0 視為 1。	1
`bytes_per_row_divisor`	`uint32`	個位元組_per_row % bytes_per_row_divisor。系統會將 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_ 維度邊界。相較於起始時不含「required_」的對應欄位，這些欄位 (設為非零值時) 表示產生的匯總非必要欄位必須指定空間，且該空格完整包含每位參與者的 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

說明圖片的表示方式。

欄位	類型	說明	預設
`pixel_format`	`PixelFormat`	像素格式。	無預設
`coded_width`	`uint32`	緩衝區中的列寬度 (以像素為單位)。必須 >= display_width。可以小於 stride_bytes 的寬度。	無預設
`coded_height`	`uint32`	列數。必須 >= display_height。	無預設
`bytes_per_row`	`uint32`	跨距 0 的位元組。飛機 0 以外的平面 (如有，視像素格式而定) 與平面 0 的步距已知關係。若是 Intel 圖塊紋理，步距適用於線性化版本的紋理。	無預設
`display_width`	`uint32`	要顯示的列寬度 (以像素為單位)。可以是 <= Code_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 是 luma (AKA Y) 樣本的像素長寬比 (AKA 樣本長寬比，又稱 SAR)。pixel_aspect_ratio 為 1:1 平均方形像素。像素_aspect_ratio 為 2:1 表示像素寬度為高度兩倍。實作轉碼器時，應視需要減少分數 (除以 GCF)，確保這兩個值相對重要。如果 has_pixel_aspect_ratio == false，則 pixel_aspect_ratio 不明。預設值 1:1 在某些情況下是適當的做法，但如同以往，取用者可能會根據 OOB 方式判斷實際的 pixel_aspect_ratio。	false
`pixel_aspect_ratio_width`	`uint32`		1
`pixel_aspect_ratio_height`	`uint32`		1

ImagePlane

定義於 fuchsia.sysmem/image_formats_Deprecatedd.fidl

欄位	類型	說明	預設
`byte_offset`	`uint32`	從圖片開頭的飛機開頭位元組偏移。	無預設
`bytes_per_row`	`uint32`	每列的跨距 (以位元組為單位)。僅適用於線性緩衝區格式。	無預設

ImageSpec

定義於 fuchsia.sysmem/image_formats_Deprecatedd.fidl

說明分配特定形式圖片的限制。

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

Node_IsAlternateFor_Response

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

PixelFormat

說明圖片像素的表示方式。簡易格式只需要類型。參數像素格式可能需要額外屬性。

欄位	類型	說明	預設
`type`	`PixelFormatType`		無預設
`has_format_modifier`	`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 資源

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

SingleBufferSettings

初始緩衝區分配後，系統即可關閉舊緩衝區並分配新的緩衝區。當配置新的緩衝區時，其設定與集合中的其餘緩衝區不同，且單一緩衝區的設定會利用以下結構，透過 OnSingleBufferAllocations() 傳遞：

欄位類型說明預設

buffer_settings BufferMemorySettings 無預設

has_image_format_constraints

bool

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

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

無預設

image_format_constraints ImageFormatConstraints 無預設

VmoBuffer 資源

欄位類型說明預設

vmo

handle<vmo>?

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

如果這是 BufferCollectionInfo_2 中屬於 BufferCollectionInfo_2.buffer_count 的 VmoBuffer，則 vmo 欄位可以是 0。

無預設

vmo_usable_start

uint64

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

無預設

ENUMS

CoherencyDomain 嚴格

類型：uint32

只有在無法存取以 CPU 為基礎的緩衝區時，才能存取緩衝區。即使 CPU 在安全模式 (或類似情況) 中執行時，CPU 只能存取 safety_required 緩衝區，仍可保有 CoherencyDomain Cpu 或 Ram 的 CoherencyDomain 緩衝區。相反地，無法從 CPU 存取的裝置本機記憶體就是 CoherencyDomain 無法存取，即使可能導致裝置 (實體或虛擬) 將資料從無法存取的緩衝區複製到 CPU 可見的緩衝區。

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

ColorSpaceType strict

類型：uint32

這份清單針對色域標準的每個變化版本，都有獨立的項目。

因此，我們是否應該新增 709 的 RGB 變體支援，例如，針對該變數，我們會在這份清單中新增一個項目。對 2020 或 2100 的 RGB 變體也類似。也同樣適用於 2020 年的 YcCbcCrc 變化版本。2100 的 ICtCp 變化版本也類似。

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

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

ColorSpaceType 的規格並未間接擴充，可支援每個樣本以外的位元數 (R、G、B 或 Y 範例)。例如，針對 2020 和 2100，系統不支援每 Y 取樣 8 位元 (由 sysmem 執行)，因為 2020 或 2100 的規格不包含 8 位元/每 Y 樣本。如果 sysmem 參與者嘗試宣傳支援的 PixelFormat + ColorSpace 這類非標準格式，將導致 sysmem 拒絕此組合並無法分配 (蓄意是極不建議指定難以定義的組合)。

名稱	值	說明
INVALID	`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 嚴格

類型：uint64

已知的堆積類型。特定裝置的類型必須設定位元 60。頂端順序位元為保留值，不應設定。

名稱	值	說明
SYSTEM_RAM	`0`
AMLOGIC_SECURE	`1152921504606912512`	用於記憶力保護記憶體的堆積。
AMLOGIC_SECURE_VDEC	`1152921504606912513`	用於解密和影片解碼期間的磁性保護記憶體的堆積。
GOLDFISH_DEVICE_LOCAL	`1152921504606978048`	金魚 vulkan 使用的堆積為裝置本機記憶體。
GOLDFISH_HOST_VISIBLE	`1152921504606978049`	金魚武裝的堆積，用來存放主機可見記憶體。
影格	`1152921504607043585`	用於顯示影格緩衝區的堆積。只有位於特定實體位址的單一影格緩衝區顯示器驅動程式會使用這項資訊。Framebuffer 堆積可讓您為 framebuffer 建立緩衝區集合，並在這些驅動程式中啟用 sysmem 支援功能。

PixelFormatType 嚴格

類型：uint32

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

這些值都具有明確性，可包含的色彩空間 (與 Vulkan 相比)。

應與 fuchsia.sysmem2.PixelFormatType 保持同步。

名稱	值	說明
INVALID	`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 (有 B 和 R 旋轉) 相容。
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，僅限 Luminance (紅色、綠色和藍色有相同的值)。與 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 位

資料表

BufferCollectionTokenGroupCreateChildRequest 資源

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

SecureHeapAndRange

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

SecureHeapAndRangeModification

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

SecureHeapAndRanges

序數	欄位	類型	說明
1	`heap`	`HeapType`	這就是受到安全/保護的堆積。
2	`ranges`	`vector<SecureHeapRange>[128]`	實體範圍清單。這份清單必須以 physical_address (優先於下方) 排序，且不得有任何重疊的範圍。可使用直接相鄰的範圍 (不得重疊)。

SecureHeapProperties

序數	欄位	類型	說明
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 用戶端就無法使用這些保留範圍。如果範圍數量受限於可用記憶體，SecureMem 伺服器可以針對這個值回報 0xFFFFFFFFFFFFFFFF。您仍須設定此欄位。一如往常，SecureMem 伺服器應能確保 SetPhysicalSecureHeapRanges() 成功或失敗 (完成前完全更新或復原)。
5	`is_mod_protected_range_available`	`bool`	如果為 true，則會實作 ModifySecureHeapPhysicalRange()。禁止在 is_mod_protect_range_available 的情況下呼叫 ModifySecureHeapPhysicalRange()。請勿嘗試透過呼叫 ModifySecureHeapPhysicalRange() 的可用性來偵測是否失敗；它可能會 ZX_PANIC()。

SecureHeapRange

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

SecureHeapsAndRanges

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

聯合國

Node_IsAlternativeFor_Result 嚴格

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

SecureMem_AddSecureHeapPhysicalRange_Result 嚴格

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

SecureMem_DeleteSecureHeapPhysicalRange_Result 嚴格

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

SecureMem_GetPhysicalSecureHeapProperties_Result 嚴格

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

SecureMem_GetPhysicalSecureHeaps_Result 嚴格

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

SecureMem_ModifySecureHeapPhysicalRange_Result 嚴格

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

SecureMem_ZeroSubRange_Result 嚴格