sdk/fidl/fuchsia.hardware.block.volume/volume.fidl - fuchsia - Git at Google

 // Copyright 2019 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 library fuchsia.hardware.block.volume;

 using fuchsia.device as device;
 using fuchsia.hardware.block.partition as partition;
 using fuchsia.io as io;
 using zx;

 /// VolumeManagerInfo describes the properties of the volume manager and not each individual volume.
 type VolumeManagerInfo = struct {
     /// Size of a single slice, in bytes.
     slice_size uint64;

     /// Number of slices the volume manager is able use right now. This counts the
     /// allocated_slice_count plus the number of available slices.
     slice_count uint64;

     /// Number of slices currently assigned to partitions.
     assigned_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 value is
     /// the number of entries reserved in the volume manager header and is not related to the size
     /// of the physical device (which may be larger or smaller).
     maximum_slice_count uint64;

     /// Largest value that can be used for a virtual slice number.
     max_virtual_slice uint64;
 };

 type VolumeInfo = struct {
     /// Number of slices allocated to the volume.
     partition_slice_count uint64;

     /// Limit on the maximum slices assigned to this partition, if there is one. If the size of the
     /// partition is not limited, this value will be 0. Partitions can grow into free slices
     /// available in the volume manager as long as their slices are less than or equal to this
     /// value.
     ///
     /// The partition may be larger than this limit if a smaller limit was applied after the
     /// partition had already grown to the current size.
     ///
     /// See `VolumeManager.GetPartitionLimit()`
     slice_limit uint64;
 };

 /// Indicates that the partition should be created as inactive, implying that it
 /// will be destroyed on reboot (unless activated by a call to "Activate").
 const ALLOCATE_PARTITION_FLAG_INACTIVE uint32 = 0x00000001;

 /// VolumeManager controls a collection of Volumes.
 closed protocol VolumeManager {
     /// 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.
     strict AllocatePartition(struct {
         slice_count uint64;
         type partition.Guid;
         instance partition.Guid;
         name string:partition.NAME_LENGTH;
         flags uint32;
     }) -> (struct {
         status zx.Status;
     });

     /// Gets the VolumeManagerInfo describing this instance of the `VolumeManager`.
     ///
     /// **NOTE**: GetInfo() is used to synchronize child partition device visibility with devfs.
     /// Implementations must only respond once all child partitions of `VolumeManager` have been
     /// added to devfs, to guarantee clients can safely enumerate them.
     ///
     /// See https://fxbug.dev/42077585 for more information.
     strict GetInfo() -> (struct {
         status zx.Status;
         info box<VolumeManagerInfo>;
     });

     /// 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.
     strict Activate(struct {
         old_guid partition.Guid;
         new_guid partition.Guid;
     }) -> (struct {
         status zx.Status;
     });

     /// 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.
     ///
     /// The partition may be larger than this limit if a smaller limit was applied after the
     /// partition had already grown to the current size.
     ///
     /// Currently the partition limit is not persisted across reboots but this may change in the
     /// future.
     strict GetPartitionLimit(struct {
         guid partition.Guid;
     }) -> (struct {
         status zx.Status;
         slice_count uint64;
     });

     /// Sets the allocation limit for the partition. Partitions can not be extended beyond their
     /// allocation limit. The partition limit will never shrink partitions so if this value is
     /// less than the current partition size, it will keep the current size but prevent further
     /// growth.
     ///
     /// 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.
     strict SetPartitionLimit(struct {
         guid partition.Guid;
         slice_count uint64;
     }) -> (struct {
         status zx.Status;
     });

     /// 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.
     strict SetPartitionName(struct {
         guid partition.Guid;
         name string:<partition.NAME_LENGTH>;
     }) -> () error zx.Status;
 };

 /// An arbitrary cap on the number of slices which may be requested when querying
 /// for allocation information from a volume.
 const MAX_SLICE_REQUESTS uint32 = 16;

 /// 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.
 type VsliceRange = struct {
     /// True if the virtual slices are allocated, false otherwise.
     allocated bool;

     /// The number of contiguous virtual slices.
     count uint64;
 };

 /// Volume is a partition which may access virtually-mapped blocks within a device.
 closed protocol Volume {
     compose partition.Partition;

     /// Returns the number of contiguous allocated (or unallocated) vslices
     /// starting from each vslice.
     ///
     // TODO(smklein): Replace array with vector; doing so would be non-simple.
     strict QuerySlices(struct {
         start_slices vector<uint64>:MAX_SLICE_REQUESTS;
     }) -> (struct {
         status zx.Status;
         response array<VsliceRange, MAX_SLICE_REQUESTS>;
         response_count uint64;
     });

     /// Returns the information about this volume and the volume manager it is embedded in.
     strict GetVolumeInfo() -> (struct {
         status zx.Status;
         manager box<VolumeManagerInfo>;
         volume box<VolumeInfo>;
     });

     /// 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).
     strict Extend(struct {
         start_slice uint64;
         slice_count uint64;
     }) -> (struct {
         status zx.Status;
     });

     /// Shrinks a virtual partition. Returns `ZX_OK` if ANY slices are
     /// freed, even if part of the requested range contains unallocated slices.
     strict Shrink(struct {
         start_slice uint64;
         slice_count uint64;
     }) -> (struct {
         status zx.Status;
     });

     /// Destroys the current partition, removing it from the VolumeManager, and
     /// freeing all underlying storage. The connection to the volume is also closed.
     strict Destroy() -> (struct {
         status zx.Status;
     });
 };

 /// This protocol is intended to emulate a block device.
 // TODO(https://fxbug.dev/42054916): Make this protocol test-only.
 // TODO(https://fxbug.dev/42063787): Remove this protocol entirely.
 closed protocol VolumeAndNode {
     compose Volume;
     compose io.Node;
     compose device.Controller;
 };
	// Copyright 2019 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.
	library fuchsia.hardware.block.volume;

	using fuchsia.device as device;
	using fuchsia.hardware.block.partition as partition;
	using fuchsia.io as io;
	using zx;

	/// VolumeManagerInfo describes the properties of the volume manager and not each individual volume.
	type VolumeManagerInfo = struct {
	/// Size of a single slice, in bytes.
	slice_size uint64;

	/// Number of slices the volume manager is able use right now. This counts the
	/// allocated_slice_count plus the number of available slices.
	slice_count uint64;

	/// Number of slices currently assigned to partitions.
	assigned_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 value is
	/// the number of entries reserved in the volume manager header and is not related to the size
	/// of the physical device (which may be larger or smaller).
	maximum_slice_count uint64;

	/// Largest value that can be used for a virtual slice number.
	max_virtual_slice uint64;
	};

	type VolumeInfo = struct {
	/// Number of slices allocated to the volume.
	partition_slice_count uint64;

	/// Limit on the maximum slices assigned to this partition, if there is one. If the size of the
	/// partition is not limited, this value will be 0. Partitions can grow into free slices
	/// available in the volume manager as long as their slices are less than or equal to this
	/// value.
	///
	/// The partition may be larger than this limit if a smaller limit was applied after the
	/// partition had already grown to the current size.
	///
	/// See `VolumeManager.GetPartitionLimit()`
	slice_limit uint64;
	};

	/// Indicates that the partition should be created as inactive, implying that it
	/// will be destroyed on reboot (unless activated by a call to "Activate").
	const ALLOCATE_PARTITION_FLAG_INACTIVE uint32 = 0x00000001;

	/// VolumeManager controls a collection of Volumes.
	closed protocol VolumeManager {
	/// 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.
	strict AllocatePartition(struct {
	slice_count uint64;
	type partition.Guid;
	instance partition.Guid;
	name string:partition.NAME_LENGTH;
	flags uint32;
	}) -> (struct {
	status zx.Status;
	});

	/// Gets the VolumeManagerInfo describing this instance of the `VolumeManager`.
	///
	/// NOTE: GetInfo() is used to synchronize child partition device visibility with devfs.
	/// Implementations must only respond once all child partitions of `VolumeManager` have been
	/// added to devfs, to guarantee clients can safely enumerate them.
	///
	/// See https://fxbug.dev/42077585 for more information.
	strict GetInfo() -> (struct {
	status zx.Status;
	info box<VolumeManagerInfo>;
	});

	/// 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.
	strict Activate(struct {
	old_guid partition.Guid;
	new_guid partition.Guid;
	}) -> (struct {
	status zx.Status;
	});

	/// 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.
	///
	/// The partition may be larger than this limit if a smaller limit was applied after the
	/// partition had already grown to the current size.
	///
	/// Currently the partition limit is not persisted across reboots but this may change in the
	/// future.
	strict GetPartitionLimit(struct {
	guid partition.Guid;
	}) -> (struct {
	status zx.Status;
	slice_count uint64;
	});

	/// Sets the allocation limit for the partition. Partitions can not be extended beyond their
	/// allocation limit. The partition limit will never shrink partitions so if this value is
	/// less than the current partition size, it will keep the current size but prevent further
	/// growth.
	///
	/// 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.
	strict SetPartitionLimit(struct {
	guid partition.Guid;
	slice_count uint64;
	}) -> (struct {
	status zx.Status;
	});

	/// 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.
	strict SetPartitionName(struct {
	guid partition.Guid;
	name string:<partition.NAME_LENGTH>;
	}) -> () error zx.Status;
	};

	/// An arbitrary cap on the number of slices which may be requested when querying
	/// for allocation information from a volume.
	const MAX_SLICE_REQUESTS uint32 = 16;

	/// 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.
	type VsliceRange = struct {
	/// True if the virtual slices are allocated, false otherwise.
	allocated bool;

	/// The number of contiguous virtual slices.
	count uint64;
	};

	/// Volume is a partition which may access virtually-mapped blocks within a device.
	closed protocol Volume {
	compose partition.Partition;

	/// Returns the number of contiguous allocated (or unallocated) vslices
	/// starting from each vslice.
	///
	// TODO(smklein): Replace array with vector; doing so would be non-simple.
	strict QuerySlices(struct {
	start_slices vector<uint64>:MAX_SLICE_REQUESTS;
	}) -> (struct {
	status zx.Status;
	response array<VsliceRange, MAX_SLICE_REQUESTS>;
	response_count uint64;
	});

	/// Returns the information about this volume and the volume manager it is embedded in.
	strict GetVolumeInfo() -> (struct {
	status zx.Status;
	manager box<VolumeManagerInfo>;
	volume box<VolumeInfo>;
	});

	/// 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).
	strict Extend(struct {
	start_slice uint64;
	slice_count uint64;
	}) -> (struct {
	status zx.Status;
	});

	/// Shrinks a virtual partition. Returns `ZX_OK` if ANY slices are
	/// freed, even if part of the requested range contains unallocated slices.
	strict Shrink(struct {
	start_slice uint64;
	slice_count uint64;
	}) -> (struct {
	status zx.Status;
	});

	/// Destroys the current partition, removing it from the VolumeManager, and
	/// freeing all underlying storage. The connection to the volume is also closed.
	strict Destroy() -> (struct {
	status zx.Status;
	});
	};

	/// This protocol is intended to emulate a block device.
	// TODO(https://fxbug.dev/42054916): Make this protocol test-only.
	// TODO(https://fxbug.dev/42063787): Remove this protocol entirely.
	closed protocol VolumeAndNode {
	compose Volume;
	compose io.Node;
	compose device.Controller;
	};