fuchsia.storage.block

新增：HEAD

通訊協定

封鎖

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

定義裝置的存取權，可讀取及寫入區塊粒度區塊。

ConnectMapper

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

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

要求

名稱類型
server_end server_end:Mapper

回應

名稱類型
payload Block_ConnectMapper_Result

刪除

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

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

要求

<EMPTY>

回應

名稱類型
status zx/Status

延長

擴展這個分割區的對應。

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

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

要求

名稱類型
start_slice uint64
slice_count uint64

回應

名稱類型
status zx/Status

GetInfo

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

要求

<EMPTY>

回應

名稱類型
payload Block_GetInfo_Result

GetInstanceGuid

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

要求

<EMPTY>

回應

名稱類型
status zx/Status
guid Guid?

GetMetadata

取得分區的中繼資料。

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

要求

<EMPTY>

回應

名稱類型
payload Block_GetMetadata_Result

GetName

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

要求

<EMPTY>

回應

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

GetTypeGuid

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

要求

<EMPTY>

回應

名稱類型
status zx/Status
guid Guid?

GetVolumeInfo

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

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

要求

<EMPTY>

回應

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

OpenSession

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

要求

名稱類型
session server_end:Session

OpenSessionWithOptions

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

對應

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

這個介面適用於巢狀 Block 實作項目之間的內部用途，可提供直通 I/O。舉例來說，固定分割區對應 (例如 GPT) 會為每個分割區提供 Block 通訊協定，並透過在基礎區塊裝置上呼叫 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/Status
response array<VsliceRange, 16>
response_count uint64

縮小

縮減虛擬分割區。如果釋放「任何」切片，即使要求範圍的部分切片未獲分配，也會傳回 ZX_OK。

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

要求

名稱類型
start_slice uint64
slice_count uint64

回應

名稱類型
status zx/Status

對應工具

定義於 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 後，用戶端不得傳送任何其他要求。

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

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

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

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

工作階段

定義於 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 後，用戶端不得傳送任何其他要求。

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

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

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

GetFifo

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

要求

<EMPTY>

回應

名稱類型
payload Session_GetFifo_Result

VolumeManager

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

VolumeManager 會控制 Volume 集合。

啟用

Atomically marks a vpartition (by instance GUID) as inactive, while finding another partition (by instance GUID) and marking it as active.

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

這項函式不會毀損「舊」分割區，只會將其標示為非使用中，如要回收該空間，必須明確毀損「舊」分割區。FVM 驅動程式重新繫結時 (即重新啟動時)，也會自動發生這項毀損情況。

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

要求

名稱類型
old_guid Guid
new_guid Guid

回應

名稱類型
status zx/Status

AllocatePartition

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

slice_count 是指最初分配給分區的切片數量，位於偏移量零。分配給新分區的切片數量不得少於一。 type 和 value 分別表示分割區的類型和執行個體 GUID。 name 表示新分區的名稱。

要求

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

回應

名稱類型
status zx/Status

GetInfo

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

NOTE：GetInfo() 用於將子分割區裝置瀏覽權限與 devfs 同步處理。 實作項目必須等到 VolumeManager 的所有子分割區都已新增至 devfs 後，才能回覆，確保用戶端可以安全地列舉這些項目。

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

要求

<EMPTY>

回應

名稱類型
status zx/Status
info VolumeManagerInfo?

GetPartitionLimit

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

如果分區已成長至目前大小，之後才套用較小的限制，分區可能會大於這個限制。

目前，分割區限制不會在重新啟動後保留，但未來可能會有所變更。

要求

名稱類型
guid Guid

回應

名稱類型
status zx/Status
slice_count uint64

SetPartitionLimit

設定分割區的分配限制。分區不得超出分配限制。分區大小上限永遠不會縮小分區，因此如果這個值小於目前的分區大小，分區會維持目前大小，但不會再擴大。

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

目前，分割區限制不會在重新啟動後保留，但未來可能會有所變更。

要求

名稱類型
guid Guid
slice_count uint64

回應

名稱類型
status zx/Status

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>

Mapper_OpenSession_Response

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

<EMPTY>

Session_AttachVmo_Response

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

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

Session_GetFifo_Response resource

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

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

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

如果包含 Volume Manager 的磁碟分割區擴充 (也就是說，Volume Manager 是在已超出原始分配容量的 GPT 磁碟分割區上初始化)，Volume Manager 可擴充至的最大容量。這個值是磁碟區管理員標頭中預留的項目數量，與實體裝置的大小無關 (可能大於或小於)。

 無預設值
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

連續虛擬切片的數量。

 無預設值

ENUMS

BlockOpcode strict

類型：uint8

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

用於 FIFO 要求的作業碼。

名稱值說明
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

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

分區表項目標記 (例如在 GPT 分區中，GPT 分區表項目標記)。請注意，這與 BlockInfo 中傳回的裝置標記不同。如果是複合分區，則不會有這個欄位。

工會

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

Mapper_OpenSession_Result strict

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

序數Variant類型說明
response Mapper_OpenSession_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

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

裝置支援修剪功能。
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. 傳送 [N - 1] 則訊息，並為任何值 1 <= N 分配 groupid。 這些郵件會加上 GROUP_ITEM 旗標。
  2. 使用相同的 groupid 傳送最後一則第 N 則訊息。這則訊息已設定 GROUP_ITEM | GROUP_LAST 旗標。
  3. 所有 N 個要求完成後，從 Block I/O 伺服器接收單一回應。所有作業完成或單一作業失敗時，系統就會傳送這項回應。此時，步驟 (1) 可能會針對相同的 groupid 再次開始。

對於 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 的本機值。