Google is committed to advancing racial equity for Black communities. See how.

fuchsia.hardware.block.volume

PROTOCOLS

BlockVolume

Defined in fuchsia.hardware.block.volume/volume.fidl

Destroy

Destroys the current partition, removing it from the Volume Manager, and freeing all underlying storage.

Request

<EMPTY>

Response

NameType
status zx/status

Extend

Attempts to extend a virtual partition.

Request

NameType
extent SliceExtent

Response

NameType
status zx/status

Query

Acquire slice size information about the parent volume.

Request

<EMPTY>

Response

NameType
status zx/status
info ParentVolumeInfo

QuerySlices

Returns the number of contiguous slices from a collection of start offsets.

Request

NameType
start vector<uint64>[16]

Response

NameType
status zx/status
responses vector<SliceRegion>[16]

Shrink

Shrinks a virtual Partition.

Request

NameType
extent SliceExtent

Response

NameType
status zx/status

Volume

Defined in fuchsia.hardware.block.volume/volume.fidl

Volume is a partition which may access virtually-mapped blocks within a device.

AttachVmo

Attaches a VMO to the currently running FIFO server.

Request

NameType
vmo handle<vmo>

Response

NameType
status zx/status
vmoid fuchsia.hardware.block/VmoId?

CloseFifo

Shuts down the fifo server, waiting for it to be ready to be started again.

When this method returns, a client may safely invoke GetFifo to acquire a new connection to the block server, without being told that a server is already serving requests on a different fifo.

If, instead of invoking "CloseFifo", a client merely closes their fifo, the server automatically cleans up all resources anyway. In this case, however, the client will have no guarantee that the next invocation of "GetFifo" will return a connection successfully.

Request

<EMPTY>

Response

NameType
status zx/status

Destroy

Destroys the current partition, removing it from the VolumeManager, and freeing all underlying storage. The connection to the volume is also closed.

Request

<EMPTY>

Response

NameType
status zx/status

Extend

Extends the mapping of this partition.

The ability to extend the partition is dependent on having sufficient free space on the underlying device, having sufficient free slots for tracking the bytes in the volume manager header, and the partition limit (see VolumeManager.SetPartitionLimit).

Request

NameType
start_slice uint64
slice_count uint64

Response

NameType
status zx/status

GetFifo

Sets up a FIFO-based server on the block device; acquire the handle to it.

Request

<EMPTY>

Response

NameType
status zx/status
fifo handle<fifo>?

GetInfo

Get information about the underlying block device.

Request

<EMPTY>

Response

NameType
status zx/status
info fuchsia.hardware.block/BlockInfo?

GetInstanceGuid

Gets the instance GUID of the partition (if one exists). If the partition has no instance GUID, ZX_ERR_NOT_SUPPORTED is returned.

Request

<EMPTY>

Response

NameType
status zx/status
guid fuchsia.hardware.block.partition/GUID?

GetName

Gets the name of the partition (if one exists). If the partition has no name, ZX_ERR_NOT_SUPPORTED is returned.

Request

<EMPTY>

Response

NameType
status zx/status
name string[128]?

GetStats

Returns stats about the block device on the provided buffer and optionally clears the counters.

Request

NameType
clear bool

Response

NameType
status zx/status
stats fuchsia.hardware.block/BlockStats?

GetTypeGuid

Gets the type GUID of the partition (if one exists). If the partition has no type GUID, ZX_ERR_NOT_SUPPORTED is returned.

Request

<EMPTY>

Response

NameType
status zx/status
guid fuchsia.hardware.block.partition/GUID?

Query

Gets slice size information about the parent volume.

Request

<EMPTY>

Response

NameType
status zx/status
info VolumeInfo?

QuerySlices

Returns the number of contiguous allocated (or unallocated) vslices starting from each vslice.

Request

NameType
start_slices vector<uint64>[16]

Response

NameType
status zx/status
response [16]
response_count uint64

RebindDevice

Rebinds the block device (if supported).

WARNING: This is only added for parity with block device ioctls; this is going to move into the device FIDL API.

Request

<EMPTY>

Response

NameType
status zx/status

Shrink

Shrinks a virtual partition. Returns ZX_OK if ANY slices are freed, even if part of the requested range contains unallocated slices.

Request

NameType
start_slice uint64
slice_count uint64

Response

NameType
status zx/status

VolumeManager

Defined in fuchsia.hardware.block.volume/volume.fidl

VolumeManager controls a collection of Volumes.

Activate

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

If the "old" partition does not exist, the GUID is ignored. If the "old" partition is the same as the "new" partition, the "old" GUID is ignored. If the "new" partition does not exist, ZX_ERR_NOT_FOUND is returned.

This function does not destroy the "old" partition, it just marks it as inactive -- to reclaim that space, the "old" partition must be explicitly destroyed. This destruction can also occur automatically when the FVM driver is rebound (i.e., on reboot).

This function may be useful for A/B updates within the FVM, since it will allow activating updated partitions.

Request

NameType
old_guid fuchsia.hardware.block.partition/GUID
new_guid fuchsia.hardware.block.partition/GUID

Response

NameType
status zx/status

AllocatePartition

Allocates a virtual partition with the requested features.

slice_count is the number of slices initially allocated to the partition, at offset zero. The number of slices allocated to a new partition must be at least one. type and value indicate type and instance GUIDs for the partition, respectively. name indicates the name of the new partition.

Request

NameType
slice_count uint64
type fuchsia.hardware.block.partition/GUID
instance fuchsia.hardware.block.partition/GUID
name string[128]
flags uint32

Response

NameType
status zx/status

GetInfo

Gets the VolumeManagerInfo describing this instance of the VolumeManager.

Request

<EMPTY>

Response

NameType
status zx/status
info VolumeManagerInfo?

GetPartitionLimit

Retrieves the allocation limit for the partition. A return value of 0 indicates that there is no limit and the partition can be extended as long as there is available space on the device.

Currently the partition limit is not persisted across reboots but this may change in the future.

Request

NameType
guid fuchsia.hardware.block.partition/GUID

Response

NameType
status zx/status
byte_count uint64

Query

Gets slice size information about all volumes.

Request

<EMPTY>

Response

NameType
status zx/status
info VolumeInfo?

SetPartitionLimit

Sets the allocation limit for the partition. Partitions can not be extended beyond their allocation limit.

The allocation limits are on the VolumeManager API rather than on the partition because they represent a higher capability level. These limits are designed to put guards on users of the block device (and hence the Volume API).

Currently the partition limit is not persisted across reboots but this may change in the future.

Request

NameType
guid fuchsia.hardware.block.partition/GUID
byte_count uint64

Response

NameType
status zx/status

SetPartitionName

Renames the specified partition. Any existing devices that include the name of the partition in their topological path might not reflect the name change until the next time that the device is instantiated.

Request

NameType
guid fuchsia.hardware.block.partition/GUID
name string[128]

Response

NameType
result VolumeManager_SetPartitionName_Result

STRUCTS

ParentVolumeInfo

Defined in fuchsia.hardware.block.volume/volume.fidl

Information about the parent device of the current volume.

FieldTypeDescriptionDefault
slice_size uint64

The size of a single slice, in bytes.

No default
virtual_slice_count uint64

The number of addressable slices within a volume.

No default
physical_slice_count_total uint64

The total number of slices which are allocatable.

No default
physical_slice_count_used uint64

The total number of slices which are allocated.

No default

SliceExtent

Defined in fuchsia.hardware.block.volume/volume.fidl

Describes an region within a Volume. Both units are in "slices".

FieldTypeDescriptionDefault
offset uint64 No default
length uint64 No default

SliceRegion

Defined in fuchsia.hardware.block.volume/volume.fidl

Information about an extent of virtual slices.

FieldTypeDescriptionDefault
allocated bool

True if the virtual slices are allocated, false otherwise.

No default
count uint64

The number of contiguous virtual slices.

No default

VolumeInfo

Defined in fuchsia.hardware.block.volume/volume.fidl

VolumeInfo describes characteristics of either a single Volume, or all Volumes combined.

FieldTypeDescriptionDefault
slice_size uint64

Size of a single slice, in bytes.

No default
vslice_count uint64

Number of addressable slices.

No default
pslice_total_count uint64

Total number of allocatable slices.

No default
pslice_allocated_count uint64

Total number of currently allocated slices.

No default

VolumeManagerInfo

Defined in fuchsia.hardware.block.volume/volume.fidl

VolumeManagerInfo describes the properties of the existing volume manager. This properties are specific for the VolumeManager and are not specific to each Volume.

FieldTypeDescriptionDefault
slice_size uint64

Size of a single slice, in bytes.

No default
current_slice_count uint64

Size in bytes of the partition the VolumeManager is able to address with respect to the available space.

No default
maximum_slice_count uint64

The maximum capacity which the Volume Manager could grow to utilize, if the partition containing the Volume Manager itself expands (i.e., the Volume Manager is initialized on a GPT partition that has extended beyond the originally allocated capacity). This resize occurs automatically on initialization of the Volume Manager, and adjusts the result of current_slice_count to reflect the currently usable size.

No default

VolumeManager_SetPartitionName_Response

Defined in fuchsia.hardware.block.volume/volume.fidl

<EMPTY>

VsliceRange

Defined in fuchsia.hardware.block.volume/volume.fidl

VsliceRange describes a range of virtual slices: start, length, and allocated status.

These ranges are returned in an ordered container, which implicitly describes the starting offset, starting from the "index zero" slice.

FieldTypeDescriptionDefault
allocated bool

True if the virtual slices are allocated, false otherwise.

No default
count uint64

The number of contiguous virtual slices.

No default

UNIONS

VolumeManager_SetPartitionName_Result strict

Defined in fuchsia.hardware.block.volume/volume.fidl

Ordinal
VariantTypeDescription
1 response VolumeManager_SetPartitionName_Response
2 err zx/status

CONSTANTS

NameValueTypeDescription
ALLOCATE_PARTITION_FLAG_INACTIVE 1 uint32

Indicates that the partition should be created as inactive, implying that it will be destroyed on reboot (unless activated by a call to "Activate").

MAX_SLICE_QUERY_REQUESTS 16 uint32
MAX_SLICE_REQUESTS 16 uint32

An arbitrary cap on the number of slices which may be requested when querying for allocation information from a volume.