sdk/fidl/fuchsia.hardware.skipblock/skip-block.fidl

// Copyright 2018 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.hardware.skipblock;

using zx;

// Matches the value of ZBI_PARTITION_GUID_LEN.
const uint32 GUID_LEN = 16;

struct PartitionInfo {
    /// Partition type GUID.
    array<uint8>:GUID_LEN partition_guid;
    /// Describes the read/write size.
    uint64 block_size_bytes;
    /// Describes size of partition in terms of blocks.
    uint32 partition_block_count;
};

struct ReadWriteOperation {
    /// Memory object describing buffer to read into or write from.
    handle<vmo> vmo;
    /// VMO offset in bytes.
    uint64 vmo_offset;
    /// Block # to begin operation from.
    uint32 block;
    /// Number of blocks to read or write.
    uint32 block_count;
};

struct WriteBytesOperation {
    /// Memory object describing buffer to write from.
    handle<vmo> vmo;
    /// VMO offset in bytes.
    uint64 vmo_offset;
    /// Device offset in bytes to begin operation from.
    /// Must be flash page aligned.
    uint64 offset;
    /// Number of bytes to write.
    /// Must be flash page aligned.
    uint64 size;
};

/// SkipBlock is a layer on top of a raw NAND device that skips bad blocks, but provides no
/// higher-level processing like wear leveling.
///
/// Skip-block partitions are used when data needs to be accessible by the bootloader. The
/// bootloader doesn't understand the more advanced FTL partitions and this data isn't written
/// frequently enough for performance or wear-leveling to be an issue.
[Layout = "Simple"]
protocol SkipBlock {
    /// Returns information about the skip-block partition.
    ///
    /// The block count can shrink in the event that a bad block is grown. It is
    /// recommended to call this again after a bad block is grown.
    GetPartitionInfo() -> (zx.status status, PartitionInfo partition_info);

    /// Reads the specified blocks into the provided vmo.
    Read(ReadWriteOperation op) -> (zx.status status);

    /// Erases and writes the specified blocks from the provided vmo.
    ///
    /// In the event that bad block is grown, the partition will shrink and
    /// `bad_block_grown` will be set to true. Since this causes the logical to
    /// physical block map to change, all previously written blocks at logical
    /// addresses after the section being written should be considered corrupted,
    /// and rewritten if applicable.
    Write(ReadWriteOperation op) -> (zx.status status, bool bad_block_grown);

    /// Erases and writes the specified bytes from the provided vmo. If offset
    /// and size in `op` are not aligned to `block_size_bytes` then the driver will
    /// first read the partitially written blocks and combine them with the
    /// provided vmo.
    ///
    /// In the event that bad block is grown, the partition will shrink and
    /// `bad_block_grown` will be set to true. Since this causes the logical to
    /// physical block map to change, all previously written blocks at logical
    /// addresses after the section being written should be considered corrupted,
    /// and rewritten if applicable.
    WriteBytes(WriteBytesOperation op) -> (zx.status status, bool bad_block_grown);
};