// 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.fs;

using fuchsia.io2;
using zx;

/// `Query` exposes objective filesystem information independent of specific
/// files and directories.
@discoverable
protocol Query {
    /// Queries the filesystem.
    ///
    /// + `query` specifies the fields in `FilesystemInfo` that the caller is
    ///   interested in.
    /// - `info` see [`fuchsia.fs/FilesystemInfo`] for details on the fields.
    ///
    GetInfo(struct {
        query FilesystemInfoQuery;
    }) -> (resource struct {
        info FilesystemInfo;
    }) error zx.status;

    /// Checks if a node is associated with this filesystem, given some token
    /// representing a connection to that node.
    IsNodeInFilesystem(resource struct {
        token zx.handle:EVENT;
    }) -> (struct {
        is_in_filesystem bool;
    });
};

/// Information about a filesystem.
///
/// If a particular field is not applicable or not supported, implementations
/// should leave it absent.
type FilesystemInfo = resource table {
    /// The number of data bytes which may be stored in the filesystem.
    1: total_bytes uint64;

    /// The number of data bytes which are in use by the filesystem.
    /// Note that this value may change in the mean time.
    2: used_bytes uint64;

    /// The number of nodes which may be stored in the filesystem.
    3: total_nodes uint64;

    /// The number of nodes used by the filesystem.
    /// Note that this value may change in the mean time.
    4: used_nodes uint64;

    /// The amount of space which may be allocated from the underlying
    /// volume manager. Note that this value may change in the mean time.
    5: free_shared_pool_bytes uint64;

    /// A globally unique identifier for this filesystem instance.
    6: fs_id zx.handle:EVENT;

    /// The size of a single filesystem block.
    7: block_size uint32;

    /// The maximum length of a filesystem name.
    8: max_node_name_size uint32;

    /// A unique identifier for the type of the underlying filesystem.
    9: fs_type FsType;

    /// The name of the filesystem.
   10: name string:MAX_FS_NAME_LENGTH;

    /// Path to the device backing this filesystem.
   11: device_path fuchsia.io2.Path;
};

/// When calling [`Query.GetInfo`], set the corresponding bit to one
/// to query a particular field.
/// The elements here correspond one-to-one with [`FilesystemInfo`].
type FilesystemInfoQuery = strict bits : uint64 {
    /// Requests [`FilesystemInfoQuery.total_bytes`].
    TOTAL_BYTES = 0x1;

    /// Requests [`FilesystemInfoQuery.used_bytes`].
    USED_BYTES = 0x2;

    /// Requests [`FilesystemInfoQuery.total_nodes`].
    TOTAL_NODES = 0x4;

    /// Requests [`FilesystemInfoQuery.used_nodes`].
    USED_NODES = 0x8;

    /// Requests [`FilesystemInfoQuery.free_shared_pool_bytes`].
    FREE_SHARED_POOL_BYTES = 0x10;

    /// Requests [`FilesystemInfoQuery.fs_id`].
    FS_ID = 0x20;

    /// Requests [`FilesystemInfoQuery.block_size`].
    BLOCK_SIZE = 0x40;

    /// Requests [`FilesystemInfoQuery.max_node_name_size`].
    MAX_NODE_NAME_SIZE = 0x80;

    /// Requests [`FilesystemInfoQuery.fs_type`].
    FS_TYPE = 0x100;

    /// Requests [`FilesystemInfoQuery.name`].
    NAME = 0x200;

    /// Requests [`FilesystemInfoQuery.device_path`].
    DEVICE_PATH = 0x400;
};

/// The maximum length of the name of a filesystem.
const MAX_FS_NAME_LENGTH uint64 = 32;

/// The type of the filesystem.
///
/// This enum should be flexible, to accommodate future additions.
type FsType = strict enum : uint32 {
    BLOBFS = 0x9e694d21;
    FACTORYFS = 0x1e694d21;
    FATFS = 0xce694d21;
    MINFS = 0x6e694d21;
    MEMFS = 0x3e694d21;
    FXFS = 0x73667866;
};