fuchsia.storage.block

新增：HEAD

通訊協定

封鎖

定義於 fuchsia.storage.block/block.fidl

定義裝置的存取權，該裝置可透過區塊精細程度區塊進行讀取和寫入。

ConnectMapper

連線至裝置的 Mapper 通訊協定，允許唯讀對應頁面。由於呼叫端已持有 Block 的控制代碼 (可授予裝置的完整讀取/寫入權限)，因此這個方法可直接取得對應的 Mapper 通訊協定，不需要頻外管道或獨立的能力轉送。

如果裝置或驅動程式庫不支援 Mapper 通訊協定，系統會傳回 ZX_ERR_NOT_SUPPORTED。

要求

名稱類型
server_end server_end:Mapper

回應

名稱類型
payload Block_ConnectMapper_Result

刪除

刪除目前的磁碟區，將其從 VolumeManager 中移除，並釋出所有基礎儲存空間。與磁碟區的連線也會關閉。

如果裝置不是磁碟區，則傳回 ZX_ERR_NOT_SUPPORTED。

要求

<EMPTY>

回應

名稱類型
status zx/Result

延長

擴充這個分區的對應。

能否擴充分區，取決於基礎裝置是否有足夠的可用空間、是否有足夠的可用運算單元來追蹤磁碟區管理員標頭中的位元組，以及分區限制 (請參閱 VolumeManager.SetPartitionLimit)。

如果裝置不是磁碟區，則傳回 ZX_ERR_NOT_SUPPORTED。

要求

名稱類型
start_slice uint64
slice_count uint64

回應

名稱類型
status zx/Result

GetInfo

取得基礎區塊裝置的相關資訊。

要求

<EMPTY>

回應

名稱類型
payload Block_GetInfo_Result

GetInstanceGuid

取得分區的執行個體 GUID (如有)。如果分區沒有執行個體 GUID，則會傳回 ZX_ERR_NOT_SUPPORTED。

要求

<EMPTY>

回應

名稱類型
status zx/Result
guid Guid?

GetMetadata

取得分區的中繼資料。

如果分區沒有指定的中繼資料，可能就不會顯示欄位。

要求

<EMPTY>

回應

名稱類型
payload Block_GetMetadata_Result

GetName

取得分區名稱 (如有)。如果分區沒有名稱，系統會傳回 ZX_ERR_NOT_SUPPORTED。

要求

<EMPTY>

回應

名稱類型
status zx/Result
name string:128?

GetTypeGuid

取得分區的類型 GUID (如果有的話)。如果分區沒有類型 GUID，則會傳回 ZX_ERR_NOT_SUPPORTED。

要求

<EMPTY>

回應

名稱類型
status zx/Result
guid Guid?

GetVolumeInfo

傳回這個磁碟區和內嵌磁碟區管理員的相關資訊。

如果裝置不是磁碟區，則傳回 ZX_ERR_NOT_SUPPORTED。

要求

<EMPTY>

回應

名稱類型
status zx/Result
manager VolumeManagerInfo?
volume VolumeInfo?

OpenSession

在區塊裝置上開啟新的 FIFO 工作階段。

要求

名稱類型
session server_end:Session

OpenSessionWithOptions

在區塊裝置上開啟新的 FIFO 工作階段，並提供其他選項。

對應

mappings 引數是邏輯 -> 實體區塊對應清單，伺服器會將其透明地套用至此工作階段中區塊 FIFO 要求中的裝置偏移。對應關係在邏輯上是連續的，從邏輯偏移 0 開始。

這個介面僅供巢狀區塊實作項目內部使用，以便提供直通式 I/O。舉例來說，固定分區對應 (例如 GPT) 會為每個分區提供區塊通訊協定，並在基礎區塊裝置上呼叫 OpenSessionWithOptions，藉此回應 OpenSession 要求，提供對應，將相對於 (且受限於) 分區的區塊偏移量轉譯為裝置上的絕對偏移量。

對應只能限制裝置的可見範圍，伺服器會拒絕超出裝置範圍的對應。

如果 mappings 為空白，工作階段管道會關閉，並顯示墓誌銘 ZX_ERR_INVALID_ARGS。

要求

名稱類型
session server_end:Session
mappings vector<BlockOffsetMapping>:4

QuerySlices

傳回從每個 vslice 開始，連續分配 (或未分配) 的 vslice 數量。

如果裝置不是磁碟區，則傳回 ZX_ERR_NOT_SUPPORTED。

要求

名稱類型
start_slices vector<uint64>:16

回應

名稱類型
status zx/Result
response array<VsliceRange, 16>
response_count uint64

縮小

縮減虛擬分區。如果釋出任何配量，即使部分要求範圍包含未分配的配量，也會傳回 ZX_OK。

如果裝置不是磁碟區，則傳回 ZX_ERR_NOT_SUPPORTED。

要求

名稱類型
start_slice uint64
slice_count uint64

回應

名稱類型
status zx/Result

Mapper

定義於 fuchsia.storage.block/block.fidl

由區塊驅動程式庫公開，透過 fshost 轉送至 pkg-cache。

OpenSession

使用對應 VMO 和驗證工具控制代碼，啟動驅動程式庫對應工具。

要求

名稱類型
session server_end:MapperSession
mapping_vmo handle<vmo>
port handle<port>?
delivery_queue handle<vmo>?

回應

名稱類型
payload Mapper_OpenSession_Result

MapperSession

定義於 fuchsia.storage.block/block.fidl

代表有效的驅動程式庫對應工作階段。

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器傳送狀態回應後，無論狀態為何，都應關閉連線，且不傳送 epitaph。

關閉管道的用戶端，在語意上應等同於呼叫 Close，而不知道關閉作業何時完成或其狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

CloseVmo

關閉與 key 相關聯、由分頁器支援的 VMO。

要求

名稱類型
key uint64

CreateVmo

建立與 key 相關聯、由翻頁元素支援的 size 位元組 VMO。這個 VMO 的分頁錯誤會直接由驅動程式庫對應器處理。

要求

名稱類型
key uint64
size uint64
options CreateVmoOptions

回應

名稱類型
payload MapperSession_CreateVmo_Result

OpenChildSession

開啟子對應器工作階段，其讀取作業會透過父項工作階段中的 parent_key 進行對應。關閉父項工作階段時，從該工作階段開啟的所有子項工作階段也會一併關閉。

要求

名稱類型
session server_end:MapperSession
mapping_vmo handle<vmo>
parent_key uint64
port handle<port>?
delivery_queue handle<vmo>?

回應

名稱類型
payload MapperSession_OpenChildSession_Result

RecordProfile

開始記錄這個對應器工作階段的存取設定檔。

要求

名稱類型
recording server_end:Recording

回應

名稱類型
payload MapperSession_RecordProfile_Result

錄音中

定義於 fuchsia.storage.block/block.fidl

代表 MapperSession 上的有效設定檔記錄。

停止

停止記錄設定檔，並在 vmo 中傳回記錄的設定檔資料 (編碼工作階段 key 和每個讀取的預讀對齊邏輯位元組偏移)。

要求

<EMPTY>

回應

名稱類型
payload Recording_Stop_Result

工作階段

定義於 fuchsia.storage.block/block.fidl

代表與區塊裝置的工作階段。

這個通訊協定會雙向編碼基礎物件的生命週期；只有在通訊協定的兩端都開啟時，基礎物件才會保持運作。也就是：

  • 關閉用戶端會導致物件遭到刪除。
  • 如果伺服器端關閉，表示物件已不存在。

您可以使用 fuchsia.unknown/Closeable.Close 同步刪除物件。

AttachVmo

將 VMO 附加至工作階段。不支援可調整大小的 VMO，並會傳回 ZX_ERR_INVALID_ARGS。

傳回可用於參照 VMO 的 ID。

要求

名稱類型
vmo handle<vmo>

回應

名稱類型
payload Session_AttachVmo_Result

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器傳送狀態回應後，無論狀態為何，都應關閉連線，且不傳送 epitaph。

關閉管道的用戶端，在語意上應等同於呼叫 Close，而不知道關閉作業何時完成或其狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

GetFifo

傳回 FIFO 用戶端端的控制代碼。

要求

<EMPTY>

回應

名稱類型
payload Session_GetFifo_Result

RegisterKey

使用這個工作階段註冊內嵌加密金鑰控制代碼 (fuchsia.hardware.inlineencryption/Device.ProgramKey 傳回的 key_token)。

傳回以工作階段為範圍的 slot 權杖，可在設定 BlockIoFlag.INLINE_ENCRYPTION_ENABLED 時傳入 BlockFifoRequest.slot。

  • 如果 key_token 不是這個區塊裝置的有效內嵌加密金鑰權杖，或金鑰已遭撤銷，則會傳回錯誤 ZX_ERR_ACCESS_DENIED。
  • 如果裝置不支援內嵌加密，則會傳回錯誤 ZX_ERR_NOT_SUPPORTED。

要求

名稱類型
key_token handle<eventpair>

回應

名稱類型
payload Session_RegisterKey_Result

VolumeManager

定義於 fuchsia.storage.block/block.fidl

VolumeManager 可控制 Volume 集合。

啟用

自動將 vpartition (依執行個體 GUID) 標示為無效，同時尋找另一個分區 (依執行個體 GUID) 並標示為有效。

如果「舊」分區不存在，系統會忽略 GUID。如果「舊」分區與「新」分區相同，系統會忽略「舊」GUID。如果「new」分區不存在，則會傳回 ZX_ERR_NOT_FOUND。

這個函式不會刪除「舊」分區，只會將其標示為不活動。如要回收該空間，必須明確刪除「舊」分區。重新繫結 FVM 驅動程式庫時 (即重新啟動時)，系統也會自動執行這項刪除作業。

這項函式可用於 FVM 內的 A/B 更新，因為它能啟用更新後的分區。

要求

名稱類型
old_guid Guid
new_guid Guid

回應

名稱類型
status zx/Result

AllocatePartition

分配具有要求功能的虛擬分區。

slice_count 是最初分配給分區的切片數量，偏移量為零。分配給新分區的切片數量至少須為一個。type 和 value 分別代表分區的類型和執行個體 GUID。name 是新分區的名稱。

要求

名稱類型
slice_count uint64
type Guid
instance Guid
name string:128
flags uint32

回應

名稱類型
status zx/Result

GetInfo

取得描述這個 VolumeManager 例項的 VolumeManagerInfo。

NOTE：GetInfo() 用於同步處理子分區裝置與 devfs 的可見度。實作項目必須在 VolumeManager 的所有子分區都新增至 devfs 後，才能回應，確保用戶端可以安全地列舉這些分區。

詳情請參閱 https://fxbug.dev/42077585。

要求

<EMPTY>

回應

名稱類型
status zx/Result
info VolumeManagerInfo?

GetPartitionLimit

擷取分區的分配限制。如果傳回值為 0，表示沒有限制，只要裝置上有可用空間，就可以擴充分區。

如果分區已達到目前大小，之後才套用較小的限制，則分區可能會大於這項限制。

目前，分區限制不會在重新啟動後保留，但日後可能會有變動。

要求

名稱類型
guid Guid

回應

名稱類型
status zx/Result
slice_count uint64

SetPartitionLimit

設定分區的分配限制。分區無法擴充超過分配限制。分區限制絕不會縮減分區，因此如果這個值小於目前的分區大小，系統會保留目前的大小，但不會進一步增加。

分配限制是針對 VolumeManager API，而非分區，因為這代表更高的能力層級。這些限制旨在保護區塊裝置 (以及 Volume API) 的使用者。

目前，分區限制不會在重新啟動後保留，但日後可能會有變動。

要求

名稱類型
guid Guid
slice_count uint64

回應

名稱類型
status zx/Result

SetPartitionName

重新命名指定的分區。如果現有裝置的拓撲路徑包含分區名稱，則可能不會反映名稱變更，直到下次例項化裝置為止。

要求

名稱類型
guid Guid
name string:128

回應

名稱類型
payload VolumeManager_SetPartitionName_Result

STRUCTS

BlockInfo

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
block_count uint64

這個區塊裝置中的區塊數量。

 無預設值
block_size uint32

單一區塊的大小。

 無預設值
max_transfer_size uint32

轉移作業的大小上限 (以位元組為單位)。如果沒有這類上限，請設為 MAX_TRANSFER_UNBOUNDED。

 無預設值
flags DeviceFlag

裝置 ID。

 無預設值

BlockOffsetMapping

定義於 fuchsia.storage.block/block.fidl

說明區塊範圍的重新對應。邏輯偏移量是由傳遞至 OpenSessionWithOptions 的清單中的位置隱含，這是邏輯上連續的對應清單。請注意，所有欄位都以區塊為單位，而非位元組。

欄位類型說明預設
target_block_offset uint64 無預設值
length uint64 無預設值

Block_ConnectMapper_Response

定義於 fuchsia.storage.block/block.fidl

<EMPTY>

Block_GetInfo_Response

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
info BlockInfo 無預設值

Guid

定義於 fuchsia.storage.block/block.fidl

全域專屬 ID，可用於識別分區。

欄位類型說明預設
value array<uint8, 16> 無預設值

MapperSession_CreateVmo_Response resource

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
vmo handle<vmo> 無預設值

MapperSession_OpenChildSession_Response

定義於 fuchsia.storage.block/block.fidl

<EMPTY>

MapperSession_RecordProfile_Response

定義於 fuchsia.storage.block/block.fidl

<EMPTY>

Mapper_OpenSession_Response

定義於 fuchsia.storage.block/block.fidl

<EMPTY>

Recording_Stop_Response 資源

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
vmo handle<vmo> 無預設值

Session_AttachVmo_Response

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
vmoid VmoId 無預設值

Session_GetFifo_Response 資源

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
fifo handle<fifo> 無預設值

Session_RegisterKey_Response

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
slot uint8 無預設值

VmoId

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
id uint16 無預設值

VolumeInfo

定義於 fuchsia.storage.block/block.fidl

欄位類型說明預設
partition_slice_count uint64

分配給磁碟區的分區數量。

 無預設值
slice_limit uint64

指派給這個分區的切片數量上限 (如有)。如果未限制分區大小，這個值會是 0。只要分區的切片數量小於或等於這個值，分區就能擴充為磁碟區管理員中的可用切片。

如果分區已達到目前大小，之後才套用較小的限制，則分區可能會大於這項限制。

查看VolumeManager.GetPartitionLimit()

 無預設值

VolumeManagerInfo

定義於 fuchsia.storage.block/block.fidl

VolumeManagerInfo 描述的是磁碟區管理員的屬性，而非個別磁碟區。

欄位類型說明預設
slice_size uint64

單一配量的大小，以位元組為單位。

 無預設值
slice_count uint64

磁碟區管理員目前可使用的磁碟區數量。這項指標會計算 allocated_slice_count 加上可用配量數。

 無預設值
assigned_slice_count uint64

目前指派給分區的切片數量。

 無預設值
maximum_slice_count uint64

如果包含磁碟區管理員本身的磁碟分割擴充 (即磁碟區管理員在 GPT 磁碟分割上初始化，且該磁碟分割已超出原本分配的容量)，磁碟區管理員可擴充使用的容量上限。這個值是磁碟區管理工具標頭中保留的項目數量，與實體裝置的大小無關 (可能較大或較小)。

 無預設值
max_virtual_slice uint64

虛擬切片編號可使用的最大值。

 無預設值

VolumeManager_SetPartitionName_Response

定義於 fuchsia.storage.block/block.fidl

<EMPTY>

VsliceRange

定義於 fuchsia.storage.block/block.fidl

VsliceRange 描述虛擬切片的範圍：開始、長度和分配狀態。

這些範圍會以排序容器的形式傳回，隱含描述起始偏移量，從「索引零」切片開始。

欄位類型說明預設
allocated bool

如果已分配虛擬切片，則為 True，否則為 False。

 無預設值
count uint64

連續虛擬切片的數量。

 無預設值

列舉

BlockOpcode strict

類型：uint8

定義於 fuchsia.storage.block/block.fidl

FIFO 要求中使用的 opcode。

名稱值說明
1

定期從裝置讀取或寫入資料。作業可能會在內部快取。
2
3

將所有控制器或裝置快取資料寫入非揮發性儲存空間。
4

指示裝置將多個區塊設為無效，以便用於儲存其他內容。這基本上是「刪除」最佳化，裝置會負責捨棄舊內容，用戶端不必寫入特定模式。作業可能會在內部快取。
5

從區塊裝置卸載 VMO。

TABLES

PartitionInfo

定義於 fuchsia.storage.block/block.fidl

描述分區的中繼資料。

序數欄位類型說明
name string:128
type_guid Guid
instance_guid Guid
start_block_offset uint64

如果分區是由多個實體分區組成，則不會有 start_block_offset。請參閱 fuchsia.storage.partitions.OverlayPartition。
num_blocks uint64

如果分區是磁碟區，則不會有 num_blocks，因為磁碟區的大小會動態調整，並可透過 fuchsia.storage.block.Block/Extend 擴充。如要取得目前大小，請使用 fuchsia.storage.block.Block/GetVolumeInfo。
flags uint64

分區資料表項目旗標 (例如 GPT 分區中的 GPT 分區資料表項目旗標)。請注意，這與 BlockInfo 傳回的裝置旗標不同。複合分區不會顯示這個欄位。

UNIONS

Block_ConnectMapper_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response Block_ConnectMapper_Response
err zx/Status

Block_GetInfo_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response Block_GetInfo_Response
err zx/Status

Block_GetMetadata_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response PartitionInfo
err zx/Status

MapperSession_CreateVmo_Result strict resource

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response MapperSession_CreateVmo_Response
err zx/Status
framework_err internal

MapperSession_OpenChildSession_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response MapperSession_OpenChildSession_Response
err zx/Status
framework_err internal

MapperSession_RecordProfile_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response MapperSession_RecordProfile_Response
err zx/Status
framework_err internal

Mapper_OpenSession_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response Mapper_OpenSession_Response
err zx/Status
framework_err internal

Recording_Stop_Result strict resource

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response Recording_Stop_Response
err zx/Status
framework_err internal

Session_AttachVmo_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response Session_AttachVmo_Response
err zx/Status

Session_GetFifo_Result strict resource

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response Session_GetFifo_Response
err zx/Status

Session_RegisterKey_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response Session_RegisterKey_Response
err zx/Status

VolumeManager_SetPartitionName_Result strict

定義於 fuchsia.storage.block/block.fidl

序數Variant類型說明
response VolumeManager_SetPartitionName_Response
err zx/Status

BITS

BlockIoFlag strict

類型：uint32

定義於 fuchsia.storage.block/block.fidl

可能附加至 FIFO 要求的標記。

名稱值說明
1

將下列要求與 group 建立關聯。
2

只有在這項要求 (以及群組內所有先前的要求) 完成後，才回應。僅適用於 GROUP_ITEM。
4

將這項作業標示為「強制單元存取」(FUA)，表示在資料寫入非揮發性媒體 (寫入) 之前，不應完成這項作業，且讀取作業應略過任何裝置端快取。
8

將預先屏障附加至要求。這可確保在這項要求之前執行的要求，不會重新排序到這項要求之後執行。

注意：屏障「不」保證傳輸中要求的順序。用戶端尚未收到回應的要求，都會視為處理中，且不保證與這項要求的相對順序。這對分組要求有重要影響：如果群組中間的要求設定了 PRE_BARRIER，則無法保證該要求與同一群組中其他要求的順序。
16

如果設定，系統會解壓縮要求。
32

使用 slot 和 dun 內嵌加密 (寫入) 或解密 (讀取) 參數。只有在基礎硬體支援內嵌加密時，才能使用。

CreateVmoOptions strict

類型：uint32

定義於 fuchsia.storage.block/block.fidl

「MapperSession.CreateVmo」的選項。

名稱值說明
1

如果設定，頁面錯誤期間的 I/O 錯誤會提供零填補頁面，並在 VMO 上宣告 ZX_USER_SIGNAL_0，而不是失敗頁面要求 ZX_ERR_IO。

DeviceFlag strict

類型：uint32

定義於 fuchsia.storage.block/block.fidl

名稱值說明
1

所有寫入區塊裝置的作業都會失敗。
2

區塊裝置可能會在作業期間從裝置中移除。
8

裝置支援 Trim。
16

裝置支援強制單元存取 (FUA)。

如果未設定這個位元，且傳送的要求已設定 FORCE_ACCESS 選項，裝置會在要求完成後 (但在回應用戶端之前) 執行裝置清除作業，模擬 FUA。強烈建議用戶端探測 FUA 支援，並避免在沒有裝置支援的情況下使用 FORCE_ACCESS，因為這項操作的成本很高。
32

裝置支援 zstd 解壓縮。
64

裝置提供 Barrier 支援。

如果未設定這個位元，且傳送的要求已設定 PRE_BARRIER 選項，裝置會在提交要求前執行裝置清除作業，模擬屏障。強烈建議用戶端探測屏障支援，並避免在沒有裝置支援的情況下使用 PRE_BARRIER，因為這項操作的成本很高。

常數

名稱值類型說明
ALLOCATE_PARTITION_FLAG_INACTIVE 1 uint32

表示分區應建立為無效，這代表分區會在重新啟動時刪除 (除非呼叫「Activate」啟用)。
GUID_LENGTH 16 uint32
MAX_DECOMPRESSED_BYTES 134217728 uint64

單一解壓縮作業群組中可解壓縮的資料量上限。
MAX_MAPPINGS 4 uint32

開啟工作階段時，可提供的區塊偏移對應數量上限。這項限制是任意設定，可視需要提高。
MAX_SLICE_REQUESTS 16 uint32

查詢磁碟區的分配資訊時，可要求的切片數量上限。
MAX_TRANSFER_UNBOUNDED 4294967295 uint32

傳輸大小的最大值，表示單一作業實際上沒有最大值。
MAX_TXN_GROUP_COUNT 8 uint32

在實際傳回回應之前，系統可能會一次傳送多個區塊 I/O 作業。區塊 I/O 作業可能會同時傳送至不同的 vmoid，也可能在任何時間點傳送至不同的群組。

MAX_TXN_GROUP_COUNT「群組」是預先分配的通道，在區塊伺服器上分隔。使用群組可讓多則訊息在單一通訊管道上同時緩衝，然後再接收回覆。

群組的使用情形由 GROUP_ITEM 旗標識別，為選用項目。

這些群組可能會以「groupid」表示，範圍為 [0, MAX_TXN_GROUP_COUNT)。

與單一群組通訊的通訊協定如下：

  1. SEND [N - 1] messages with an allocated groupid for any value of 1 <= N. 系統會為這些郵件設定 GROUP_ITEM 標記。
  2. 傳送具有相同 groupid 的最後一則訊息。這則訊息已設定 GROUP_ITEM | GROUP_LAST 標記。
  3. 在所有 N 個要求完成後，從區塊 I/O 伺服器接收單一回應。所有作業完成或單一作業失敗時，系統就會傳送這項回應。此時，系統可能會再次針對同一個 groupid 執行步驟 (1)。

對於 READ 和 WRITE，N 可能大於 1。否則 N == 1 (略過上述通訊協定中的步驟 (1))。

注意：

  • groupids 可同時對任意數量的 vmoids 執行操作。
  • 如果在步驟 (3) 完成前，系統收到相同 groupid 的其他要求，則不會處理這些要求。如果設定 GROUP_LAST，系統會傳回錯誤。否則，系統會自動捨棄要求。
  • 系統不保證會依任何順序處理群組內的訊息。
  • 除了未設定 GROUP_LAST 的 GROUP_ITEM 要求外，所有要求都會收到回應。

舉例來說，以下是有效的交易序列：

-> (groupid = 1, vmoid = 1, OP = Write | GroupItem, reqid = 1) -> (groupid = 1, vmoid = 2, OP = Write | GroupItem, reqid = 2) -> (groupid = 2, vmoid = 3, OP = Write | GroupItem | GroupLast, reqid = 0) <- Response sent to groupid = 2, reqid = 0 -> (groupid = 1, vmoid = 1, OP = Read | GroupItem | GroupLast, reqid = 3) <- Response sent to groupid = 1, reqid = 3 -> (groupid = 3, vmoid = 1, OP = Write | GroupItem, reqid = 4) -> (groupid = don't care, vmoid = 1, OP = Read, reqid = 5) <- Response sent to reqid = 5 -> (groupid = 3, vmoid = 1, OP = Read | GroupItem | GroupLast, reqid = 6) <- Response sent to groupid = 3, reqid = 6

每筆交易都會從裝置讀取或寫入最多 length 個區塊 (從 dev_offset 個區塊開始)，並寫入與 vmoid 相關聯的 VMO (從 vmo_offset 個區塊開始)。如果交易超出範圍，例如 length 太大，或 dev_offset 超出裝置結尾，則會傳回 ZX_ERR_OUT_OF_RANGE。
NAME_LENGTH 128 uint32
VMOID_INVALID 0 uint16

為「無效」VmoId 保留的值。伺服器一律不會分配這個 ID，且這個 ID 可做為未分配 ID 的本機值。