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

#pragma once

#include <lib/mtd/nand-interface.h>
#include <zircon/types.h>

#include <cstdint>
#include <vector>

namespace nand_rs {

// Base interface for a NAND-based redundant storage writer/reader.
class NandRedundantStorageInterface {
 public:
  virtual ~NandRedundantStorageInterface() {}

  // Writes a buffer to the NAND storage device.
  //
  // This overwrites anything stored on the device on the block level, and can
  // potentially erase the entire device's storage even when requesting to
  // store a single copy of a small file.
  //
  // Requires a non-empty buffer that is at least 12-bytes smaller than the
  // erase block size (this leaves room for a recovery header).
  //
  // |num_copies| must be no larger than the total NAND interface's storage
  // capacity divided by the erase block size.
  //
  // |num_copies_written| returns the number of copies successfully written.
  //
  // |skip_recovery_header| skips writing the recovery header.
  //
  // Each copy of the buffer will be stored on one erase block of the NAND
  // device with an included 12 byte recovery header. The header is not
  // written if |skip_recovery_header| is true.
  //
  // Return Values:
  // --------------
  //
  // ZX_OK -- in the event that at least one copy of |buffer| is written to
  //          the NAND interface successfully. The total number of copies
  //          will be written to the out variable |num_copies_written|.
  //
  // ZX_ERR_NO_SPACE -- in the event that it is not possible to write any
  //                    copies. This would be if there are absolutely no good
  //                    blocks on the NAND interface.
  virtual zx_status_t WriteBuffer(const std::vector<uint8_t>& buffer, uint32_t num_copies,
                                  uint32_t* num_copies_written,
                                  bool skip_recovery_header = false) = 0;

  // Attempts to read from a NAND interface previously written to with
  // WriteBuffer.
  //
  // |out_buffer| out pointer where the contents stored in the NAND interface
  // sans 12-byte header is written.
  //
  // |skip_recovery_header| Reads the NAND interface assuming there is not a
  // recovery header. If true then |file_size| must be set.
  //
  // |file_size| Total byte count of the contents. Required to read contents
  // when a recovery header is not available.
  //
  // Return Values:
  // --------------
  //
  // ZX_OK -- NAND interface was successfully read, and |out_buffer| has
  //          the content sans 12-byte header written .
  //
  // ZX_INVALID_ARGS -- |skip_recovery_header| is true, but file_size was not
  //                    set.
  //
  // ZX_ERR_IO -- It is not possible to write the contents into |out_buffer|.
  //
  // *WARNING* if |skip_recovery_header| is true no data integrity checks can
  // be ran against the read data. Integrity checks should be performed by the
  // consumer of this library.
  virtual zx_status_t ReadToBuffer(std::vector<uint8_t>* out_buffer,
                                   bool skip_recovery_header = false, size_t file_size = 0) = 0;
};

}  // namespace nand_rs