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;

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

type Success = struct {};

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

/// Use `InvalidAddress` instead.
@deprecated
type ReaderOutOfBounds = struct {
    /// Byte position in filesystem image.
    position uint64;
    /// Size of image.
    size uint64;
};

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

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

/// Result of an [`Ext4Server.MountVmo`] call.
type MountVmoResult = flexible union {
    // 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: vmo_read_failure zx.status;

    3: parse_error ParseError;
};

@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(resource struct {
        source fuchsia.mem.Buffer;
        flags fuchsia.io.OpenFlags;
        root server_end:fuchsia.io.Directory;
    }) -> (struct {
        result MountVmoResult;
    });
};

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