sdk/fidl/fuchsia.fshost/fshost.fidl

// 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.
@available(added=HEAD)
library fuchsia.fshost;

using zx;
using fuchsia.fxfs;
using fuchsia.io;
using fuchsia.storage.partitions;

type MountOptions = resource table {
    1: read_only bool;
    /// [DEPRECATED] Metrics are always enabled now.
    // TODO(https://fxbug.dev/42172184): Remove.
    2: collect_metrics bool;
    3: verbose bool;
    4: write_compression_algorithm string:32;
};

/// Manages fshost lifecycle
@discoverable
closed protocol Admin {
    /// Wipes the data volume which will get reinitialised upon next boot.  This is not
    /// cryptographically secure; the caller should take care to reset hardware keys.
    strict ShredDataVolume() -> () error zx.Status;

    /// Returns whether fshost is configured to use storage-host.
    // TODO(https://fxbug.dev/339491886): Remove once storage-host is always enabled.
    strict StorageHostEnabled() -> (struct {
        enabled bool;
    });
};

/// Special functionality that is only intended to be used in recovery and device bringup.
///
/// *WARNING*: The methods in this protocol are highly specialized and can result in unintended
/// data loss if used improperly. Most methods in this protocol assume exclusive access to the
/// underlying block device, and it is the responsibility of callers to mediate the use of this
/// protocol across components.
// TODO(https://fxbug.dev/444486641): Determine if we should add a way to synchronize clients that
// use this protocol to unintended concurrent usage. Right now consumers of the protocol are
// required to manage shared access to the underlying system container and unmount filesystems
// manually.
@discoverable
closed protocol Recovery {
    /// Wipes and re-initializes the system partition table.  This is a destructive operation!
    strict InitSystemPartitionTable(struct {
        partitions
                vector<fuchsia.storage.partitions.PartitionInfo>:fuchsia.storage.partitions.MAX_PARTITIONS;
    }) -> () error zx.Status;

    /// Writes `filename` into the data partition with contents from `payload`, formatting the data
    /// partition if it isn't already formatted.  Overwrites file if it already exists.
    ///
    /// This can only be called while the data partition isn't already mounted, which is typically
    /// in recovery builds where fshost is running with the `ramdisk_image` flag set.
    strict WriteDataFile(resource struct {
        filename fuchsia.io.Path;
        payload zx.Handle:VMO;
    }) -> () error zx.Status;

    /// Formats the blob volume in the system container. If the system container does not have a
    /// blob volume, a new one will be created. All existing blobs will be deleted. If the system
    /// container is corrupt or unmountable, this function will have no effect and will leave the
    /// disk intact.
    ///
    /// **WARNING**: This can cause irreversible data loss and can render a device unbootable.
    strict FormatSystemBlobVolume() -> () error zx.Status;

    /// Mounts the system container's blob volume, and returns a handle to the blob volume's
    /// exposed directory to facilitate writing a new system. The system container will remain
    /// mounted as long as `blob_exposed_dir` is kept open. Only the blob volume will be mounted.
    strict MountSystemBlobVolume(resource struct {
        blob_exposed_dir server_end:<fuchsia.io.Directory>;
    }) -> () error zx.Status;
};

/// Provides access to the volume which will be used by Starnix to store its data.
@discoverable
closed protocol StarnixVolumeProvider {
    /// Mounts the main starnix volume using `crypt`. `exposed_dir` will be connected to the
    /// exposed directory of the mounted starnix volume. Silently creates the volume if it does
    /// not already exist.
    strict Mount(resource struct {
        crypt client_end:fuchsia.fxfs.Crypt;
        exposed_dir server_end:fuchsia.io.Directory;
    }) -> () error zx.Status;

    /// Creates and mounts the main starnix volume using `crypt`. If the volume already exists,
    /// unmount and delete the volume before creating the new one. `exposed_dir` will be connected
    /// to the exposed directory of the mounted starnix volume.
    strict Create(resource struct {
        crypt client_end:fuchsia.fxfs.Crypt;
        exposed_dir server_end:fuchsia.io.Directory;
    }) -> () error zx.Status;
};