// 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.nand;
using fuchsia.hardware.nand;
using zx;

// Defines a Read/Write/Erase request to be sent to the nand driver.
type BrokerRequestData = resource struct {
    vmo zx.Handle:<VMO, optional>; // Only used for read and write.
    length uint32; // In pages (read / write) or blocks (erase).
    offset_nand uint32; // In pages (read / write) or blocks (erase).
    offset_data_vmo uint64; // In pages.
    offset_oob_vmo uint64; // In pages.
    data_vmo bool; // True to read or write data.
    oob_vmo bool; // True to read or write OOB data.
};

type BrokerRequestDataBytes = resource struct {
    vmo zx.Handle:<VMO>; // Only used for read and write.
    length uint64; // In bytes.
    offset_nand uint64; // In bytes.
    offset_data_vmo uint64; // In bytes.
};

/// The Broker allows for serialized entry to the raw nand, which ensures only a single client is
/// ever talking to the nand device, and all higher level clients have disconnected. In addition,
/// access to raw nand is restricted from the system during production where nand-broker is not
/// present.
closed protocol Broker {
    // Retrieves the nand info from the underlying device.
    strict GetInfo() -> (struct {
        status zx.Status;
        info box<fuchsia.hardware.nand.Info>;
    });

    // Reads from the nand device.
    strict Read(resource struct {
        request BrokerRequestData;
    }) -> (struct {
        status zx.Status;
        corrected_bit_flips uint32;
    });

    // Writes to the nand device.
    strict Write(resource struct {
        request BrokerRequestData;
    }) -> (struct {
        status zx.Status;
    });

    // Reads from the nand device.
    strict ReadBytes(resource struct {
        request BrokerRequestDataBytes;
    }) -> (struct {
        status zx.Status;
    });

    // Writes to the nand device.
    strict WriteBytes(resource struct {
        request BrokerRequestDataBytes;
    }) -> (struct {
        status zx.Status;
    });

    // Erases part of the nand device.
    strict Erase(resource struct {
        request BrokerRequestData;
    }) -> (struct {
        status zx.Status;
    });
};