// Copyright 2020 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.rpmb;

using zx;
using fuchsia.mem;

// RPMB: Replay Protected Memory Block
// RPMB is a secure area included in certain types of storage devices. For more information, see:
// https://optee.readthedocs.io/en/latest/architecture/secure_storage.html#rpmb-secure-storage

/// The RPMB frame size in bytes.
const uint32 FRAME_SIZE = 512;

struct EmmcDeviceInfo {
    /// The device's CID register.
    array<uint8>:16 cid;
    /// RPMB_SIZE_MULT from the device's EXT_CSD register.
    uint8 rpmb_size;
    /// REL_WR_SEC_C from the device's EXT_CSD register.
    uint8 reliable_write_sector_count;
};

flexible union DeviceInfo {
    1: EmmcDeviceInfo emmc_info;
};

/// Represents an RPMB operation, which consists of sending one or more frames then receiving zero
/// or more frames. The tx_frames and rx_frames VMOs will be transferred to the protocol
/// implementation, so clients should keep duplicates of them if access is needed after the call to
/// Request().
/// The request will be aborted as soon as an error is encountered, meaning the read operation will
/// not be performed if the write operation failed. Invalid parameters passed through tx_frames or
/// rx_frames will cause an error to be returned immediately, without either operation having been
/// performed.
resource struct Request {
    /// May not be null as all operations involve sending at least one frame. tx_frames.size must be
    /// a multiple of and at least FRAME_SIZE.
    fuchsia.mem.Range tx_frames;

    /// May be null if no frames need to be received. rx_frames.size must be a multiple of
    /// FRAME_SIZE if rx_frames is not null.
    fuchsia.mem.Range? rx_frames;
};

protocol Rpmb {
    GetDeviceInfo() -> (DeviceInfo info);
    Request(Request request) -> () error zx.status;
};