// 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.nand;

using zx;

const MAX_PARTITIONS uint32 = 10;
const NAME_LEN uint32 = 32;

type Partition = struct {
    /// GUID specifying the format and use of data stored in the partition.
    type_guid array<uint8, GUID_LEN>;

    /// GUID unique to this partition.
    unique_guid array<uint8, GUID_LEN>;

    /// First and last block occupied by this partition.
    first_block uint32;
    last_block uint32;

    /// The number of data copies and offset between each data copy (if relevant).
    copy_count uint32;
    copy_byte_offset uint32;

    // A string would break the current requirement for a simple C binding.
    name array<uint8, NAME_LEN>;

    /// Not a user-visible partition.
    hidden bool;

    /// Contains a legacy bad block table.
    bbt bool;
};

type PartitionMap = struct {
    device_guid array<uint8, GUID_LEN>;

    /// Number of partitions in the map.
    partition_count uint32;
    partitions array<Partition, MAX_PARTITIONS>;
};

/// Defines how a newly created ram-nand volume should operate.
type RamNandInfo = resource struct {
    /// VMO to use as backing store for nand device. Size should match size of `nand_info`.
    /// If a vmo is not provided, the device will create its own buffer and initialize it to be
    /// empty (all 1s).
    vmo zx.Handle:<VMO, optional>;

    /// The desired "chip" configuration.
    nand_info Info;

    /// Partition map for the device. This can be left fully empty (as in default-initialized),
    /// as long as no metadata has to be exported by the device. If any metadata is required,
    /// it will be extracted from this map.
    partition_map PartitionMap;

    /// If true, export "extra" partition configuration as metadata.
    export_nand_config bool;
    /// if true, export a boot partition map as metadata.
    export_partition_map bool;

    /// If non-zero, fail after `fail_after` writes.
    fail_after uint32;

    /// The vmo to store block erase counts in. If this vmo is present then it must be at least
    /// large enough to hold a uint32_t per Info.num_blocks. The values will not be zeroed when the
    /// nand starts up, they will just be incremented in place.
    wear_vmo zx.Handle:<VMO, optional>;
};

closed protocol RamNandCtl {
    /// Creates a new ram-nand device. On success, returns the device's name (not the full
    /// topological name, just the last component).
    strict CreateDevice(resource struct {
        info RamNandInfo;
    }) -> (struct {
        status zx.Status;
        name string:NAME_LEN;
    });
};

closed protocol RamNand {
    /// Removes the device.
    strict Unlink() -> (struct {
        status zx.Status;
    });
};