src/storage/ext4/server/fidl/ext4_readonly.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.

library fuchsia.storage.ext4;

using fuchsia.io;
using fuchsia.mem;
using zx;

enum OutOfBoundsDirection {
    BELOW = 1;
    ABOVE = 2;
};

struct Success {
};

struct InvalidSuperBlock {
    /// Byte position in filesystem image.
    uint64 position;
};

struct InvalidSuperBlockMagic {
    /// Magic number.
    uint16 value;
};

struct BlockNumberOutOfBounds {
    /// Block number.
    uint64 block_number;
};

struct BlockSizeInvalid {
    /// Block size.
    uint32 block_size;
};

struct InvalidBlockGroupDesc {
    /// Byte position in filesystem image.
    uint64 position;
};

struct InvalidINode {
    /// INode number.
    uint32 inode_number;
};

struct InvalidExtentHeader {
    // This will fill in in a followup change.
};

struct InvalidExtentHeaderMagic {
    /// Magic number.
    uint16 value;
};

struct InvalidExtent {
    /// Byte position in filesystem image.
    uint64 position;
};

struct ExtentUnexpectedLength {
    /// Size received.
    uint64 size;
    /// Size expected.
    uint64 expected;
};

struct InvalidDirEntry2 {
    /// Byte position in filesystem image.
    uint64 position;
};

struct DirEntry2NonUtf8 {
    /// Data that was unable to be converted into UTF-8.
    /// Limiting to 255 to match with the max filename length.
    vector<uint8>:255 data;
};

struct InvalidInputPath {
    /// Not implemented. Will be empty string.
    string:1024 path;
};

struct PathNotFound {
    /// Path given.
    string:1024 path;
};

/// Directory entry has bad type value.
struct BadEntryType {
    /// Type value.
    uint8 value;
};

/// Feature Incompatible flag has banned flags.
struct BannedFeatureIncompat {
    /// Bitwise flags that are banned.
    uint32 value;
};

/// Feature Incompatible flag has missing flags.
struct RequiredFeatureIncompat {
    /// Bitwise flags that are missing.
    uint32 value;
};

struct Incompatible {
    /// Message stating what is wrong.
    string:1024 msg;
};

struct BadFile {
    /// Path of file.
    string:1024 path;
};

struct BadDirectory {
    /// Path of directory.
    string:1024 path;
};

struct ReaderReadError {
    /// Byte position in filesystem image.
    uint64 position;
};

/// Use `InvalidAddress` instead.
[Deprecated]
struct ReaderOutOfBounds {
    /// Byte position in filesystem image.
    uint64 position;
    /// Size of image.
    uint64 size;
};

struct InvalidAddress {
    /// Byte position in filesystem image.
    uint64 position;
    /// Direction of out of bounds.
    OutOfBoundsDirection direction;
    /// Boundary that was exceeded.
    uint64 bound;
};

/// Sub-result of an [`Ext4Server.MountVmo`] call denoting the actual error
/// that occurred in the reader.
flexible union ParseError {
    // Failures during the initial parsing of the image start below.
    // See ext4_read_only::structs::ParsingError for more info.
    1: InvalidSuperBlock invalid_super_block;
    2: InvalidSuperBlockMagic invalid_super_block_magic;
    3: BlockNumberOutOfBounds block_number_out_of_bounds;
    4: BlockSizeInvalid block_size_invalid;
    5: InvalidBlockGroupDesc invalid_block_group_desc;
    6: InvalidINode invalid_inode;
    7: InvalidExtentHeader invalid_extent_header;
    8: InvalidExtentHeaderMagic invalid_extent_header_magic;
    9: InvalidExtent invalid_extent;
    10: ExtentUnexpectedLength extent_unexpected_length;
    11: InvalidDirEntry2 invalid_dir_entry_2;
    12: DirEntry2NonUtf8 dir_entry_2_non_utf8;
    13: InvalidInputPath invalid_input_path;
    14: PathNotFound path_not_found;
    15: BadEntryType bad_entry_type;
    16: Incompatible incompatible;
    17: BadFile bad_file;
    18: BadDirectory bad_directory;
    19: ReaderReadError reader_read_error;
    [Deprecated]
    20: ReaderOutOfBounds reader_out_of_bounds;
    21: RequiredFeatureIncompat required_feature_incompat;
    22: BannedFeatureIncompat banned_feature_incompat;
    23: InvalidAddress invalid_address;
};

/// Result of an [`Ext4Server.MountVmo`] call.
flexible union MountVmoResult {
    // Note: It would be better to declare `MountVmo` with a result type of
    // `() error MountVmoError`, but FIDL currently does not support error
    // types that are not integers or enums of integers.  And it is nice to be
    // able to report richer error information than just an error code.

    /// The server has managed to read the image far enough to load the
    /// root directory and none of the early validation checks have failed.
    1: Success success;

    /// Error reading the VMO.
    2: zx.status vmo_read_failure;

    3: ParseError parse_error;
};

[Discoverable]
protocol Server {
    /// Read the VMO content as an Ext4 image and return a channel to the
    /// root of the mounted file system.
    ///
    /// + request `source` is an Ext4 image to be served over the `root`
    ///            connection.
    /// + request `flags` is the same flags you can pass to
    ///            [`fuchsia.io/Directory.Open`] call.  In particular
    ///            [`OPEN_FLAG_DESCRIBE`] can be used to report mount errors.
    ///            Note that [`MountVmoError`] will contain a better
    ///            description of any error that may occur at the mount
    ///            time.
    /// + request `root` is the server end of a connection that will be
    ///            serving the root of the mounted image.
    /// - result `result` In case we could parse the image far enough to
    ///           read the root directory [`MountVmoResult.success`] will be
    ///           returned.  Note that you may pipeline requests to the
    ///           `root` connection even before received a response.  In
    ///           case of an error one of the other values will be returned
    ///           and the `root` connection will be closed.
    MountVmo(
        fuchsia.mem.Buffer source,
        uint32 flags,
        request<fuchsia.io.Directory> root
        ) -> (MountVmoResult result);
};

service Service {
    /// An Ext4 server that can parse a file system image and present it
    /// using fuchsia-io FIDL API.
    Server server;
};