// Copyright 2018 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 zx;

/// VolumeManagerInfo describes the properties of the volume manager and not each individual volume.
@for_deprecated_c_bindings
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;
};

@for_deprecated_c_bindings
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.
    ///
    /// See `VolumeManager.GetPartitionLimit()`
    slice_limit uint64;
};

/// Describes an region within a Volume. Both units are in "slices".
type SliceExtent = struct {
    offset uint64;
    length uint64;
};

const MAX_SLICE_QUERY_REQUESTS uint32 = 16;

/// Information about an extent of virtual slices.
type SliceRegion = struct {
    /// True if the virtual slices are allocated, false otherwise.
    allocated bool;
    /// The number of contiguous virtual slices.
    count uint64;
};

@transport("Banjo")
@banjo_layout("ddk-protocol")
protocol BlockVolume {
    /// Attempts to extend a virtual partition.
    Extend(struct {
        extent SliceExtent;
    }) -> (struct {
        status zx.status;
    });

    /// Shrinks a virtual Partition.
    Shrink(struct {
        extent SliceExtent;
    }) -> (struct {
        status zx.status;
    });

    // Returns the information about the volume manager 
    GetInfo() -> (struct {
        status zx.status;
        manager VolumeManagerInfo;
        volume VolumeInfo;
    });

    /// Returns the number of contiguous slices from a collection
    /// of start offsets.
    QuerySlices(struct {
        start vector<uint64>:MAX_SLICE_QUERY_REQUESTS;
    }) -> (struct {
        status zx.status;
        responses vector<SliceRegion>:MAX_SLICE_QUERY_REQUESTS;
    });

    /// Destroys the current partition, removing it from the Volume Manager, and
    /// freeing all underlying storage.
    Destroy() -> (struct {
        status zx.status;
    });
};