src/storage/fidl/fuchsia.fs.startup/startup.fidl

// Copyright 2021 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.startup;

using fuchsia.hardware.block;
using zx;

/// Compression algorithm specifier.
type CompressionAlgorithm = flexible enum {
    ZSTD_CHUNKED = 0;
    UNCOMPRESSED = 1;
};

/// An optional eviction policy override for pager-backed blobs for blobfs.
type EvictionPolicyOverride = flexible enum {
    /// Don't override the default cache policy.
    NONE = 0;
    /// Override the default cache policy for pager-backed blobs with kNeverEvict.
    NEVER_EVICT = 1;
    /// Override the default cache policy for pager-backed blobs with kEvictImmediately.
    EVICT_IMMEDIATELY = 2;
};

/// Options for starting a filesystem.
type StartOptions = resource struct {
    /// Start the filesystem in read-only mode.
    @allow_deprecated_struct_defaults
    read_only bool = false;
    /// Enable verbose logging.
    @allow_deprecated_struct_defaults
    verbose bool = false;
    /// If true, run fsck after every transaction. This is for testing purposes only - it's very
    /// slow to run a filesystem like this.
    fsck_after_every_transaction bool;

    /// A compression algorithm specifier for the filesystem to use when storing files (if the
    /// filesystem supports it). Defaults to ZSTD_CHUNKED.
    write_compression_algorithm CompressionAlgorithm;
    /// An optional compression level for the filesystem to use when storing files (if the
    /// filesystem and the configured |write_compression_algorithm| supports it). Setting to < 0
    /// indicates no value (the filesystem chooses a default if necessary).
    @allow_deprecated_struct_defaults
    write_compression_level int32 = -1;

    /// An optional eviction policy specifier for the filesystem to use for in-memory structures
    /// (if the filesystem supports it), specifically for pager-backed files.
    cache_eviction_policy_override EvictionPolicyOverride;

    /// Set greater than zero to use profiling for the first N seconds after filesystem start.
    /// Records the access patterns of objects for N seconds and if the profile already exists,
    /// prefetch data and hold the vmos in cache for N seconds. Functionally this means that the
    /// first launch with this option records the profile and all other launches with this option
    /// will replay that profile.
    /// TODO(https://fxbug.dev/328071060): Enable profile recordings access and handling.
    startup_profiling_seconds uint32;
};

/// Options for how to format filesystems.
type FormatOptions = table {
    /// Enable verbose logging.
    1: verbose bool;
    /// If true, use the deprecated padded merkle tree blobfs format.
    2: deprecated_padded_blobfs_format bool;
    /// The initial number of inodes to allocate space for. If zero, a default is used. Only
    /// supported for blobfs.
    3: num_inodes uint64;
    /// The number of fvm slices to preallocate for data when the filesystem is created.
    4: fvm_data_slices uint32;
    /// The number of sectors-per-cluster (for FAT filesystems).
    5: sectors_per_cluster uint16;
};

/// Options for running consistency checks on filesystems.
type CheckOptions = resource struct {};

// TODO(https://fxbug.dev/42172184): Figure out a more flexible configuration option strategy.
@discoverable
closed protocol Startup {
    /// Start this filesystem, using the provided block device and Start options. When start is
    /// called, the filesystem will populate its outgoing directory and then return.
    strict Start(resource struct {
        device client_end:fuchsia.hardware.block.Block;
        options StartOptions;
    }) -> () error zx.Status;

    /// Format the provided block device with this filesystem.
    strict Format(resource struct {
        device client_end:fuchsia.hardware.block.Block;
        options FormatOptions;
    }) -> () error zx.Status;

    /// Check the provided block device for filesystem consistency.
    /// Note that some filesystems (e.g. Fxfs) support online fsck, in which case they can be
    /// checked after being started.  In this case, the passed block device is ignored.
    strict Check(resource struct {
        device client_end:fuchsia.hardware.block.Block;
        options CheckOptions;
    }) -> () error zx.Status;
};