third_party/pigweed/repo/pw_kvs/public/pw_kvs/fake_flash_memory.h

   1 // Copyright 2020 The Pigweed Authors
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
   4 // use this file except in compliance with the License. You may obtain a copy of
   5 // the License at
   6 //
   7 //     https://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  12 // License for the specific language governing permissions and limitations under
  13 // the License.
  14 #pragma once
  15
  16 #include <algorithm>
  17 #include <array>
  18 #include <cstddef>
  19 #include <cstring>
  20 #include <span>
  21
  22 #include "pw_containers/vector.h"
  23 #include "pw_kvs/flash_memory.h"
  24 #include "pw_status/status.h"
  25
  26 namespace pw::kvs {
  27
  28 class FlashError {
  29  public:
  30   static constexpr FlashMemory::Address kAnyAddress = FlashMemory::Address(-1);
  31   static constexpr size_t kAlways = size_t(-1);
  32
  33   // Creates a FlashError that always triggers on the next operation.
  34   static constexpr FlashError Unconditional(Status status,
  35                                             size_t times = kAlways,
  36                                             size_t delay = 0) {
  37     return FlashError(status, kAnyAddress, 0, times, delay);
  38   }
  39
  40   // Creates a FlashError that triggers for particular addresses.
  41   static constexpr FlashError InRange(Status status,
  42                                       FlashMemory::Address address,
  43                                       size_t size = 1,
  44                                       size_t times = kAlways,
  45                                       size_t delay = 0) {
  46     return FlashError(status, address, size, times, delay);
  47   }
  48
  49   // Determines if this FlashError applies to the operation.
  50   Status Check(FlashMemory::Address start_address, size_t size);
  51
  52   // Determines if any of a series of FlashErrors applies to the operation.
  53   static Status Check(std::span<FlashError> errors,
  54                       FlashMemory::Address address,
  55                       size_t size);
  56
  57  private:
  58   constexpr FlashError(Status status,
  59                        FlashMemory::Address address,
  60                        size_t size,  // not used if address is kAnyAddress
  61                        size_t times,
  62                        size_t delay)
  63       : status_(status),
  64         begin_(address),
  65         end_(address + size),  // not used if address is kAnyAddress
  66         delay_(delay),
  67         remaining_(times) {}
  68
  69   const Status status_;
  70
  71   const FlashMemory::Address begin_;
  72   const FlashMemory::Address end_;  // exclusive
  73
  74   size_t delay_;
  75   size_t remaining_;
  76 };
  77
  78 // This uses a buffer to mimic the behaviour of flash (requires erase before
  79 // write, checks alignments, and is addressed in sectors). The underlying buffer
  80 // is not initialized.
  81 class FakeFlashMemory : public FlashMemory {
  82  public:
  83   // Default to 8-bit alignment.
  84   static constexpr size_t kDefaultAlignmentBytes = 1;
  85
  86   static constexpr std::byte kErasedValue = std::byte{0xff};
  87
  88   FakeFlashMemory(std::span<std::byte> buffer,
  89                   size_t sector_size,
  90                   size_t sector_count,
  91                   size_t alignment_bytes = kDefaultAlignmentBytes,
  92                   Vector<FlashError>& read_errors = no_errors_,
  93                   Vector<FlashError>& write_errors = no_errors_)
  94       : FlashMemory(sector_size, sector_count, alignment_bytes),
  95         buffer_(buffer),
  96         read_errors_(read_errors),
  97         write_errors_(write_errors) {}
  98
  99   // The fake flash is always enabled.
 100   Status Enable() override { return OkStatus(); }
 101
 102   Status Disable() override { return OkStatus(); }
 103
 104   bool IsEnabled() const override { return true; }
 105
 106   // Erase num_sectors starting at a given address.
 107   Status Erase(Address address, size_t num_sectors) override;
 108
 109   // Reads bytes from flash into buffer.
 110   StatusWithSize Read(Address address, std::span<std::byte> output) override;
 111
 112   // Writes bytes to flash.
 113   StatusWithSize Write(Address address,
 114                        std::span<const std::byte> data) override;
 115
 116   std::byte* FlashAddressToMcuAddress(Address) const override;
 117
 118   // Testing API
 119
 120   // Access the underlying buffer for testing purposes. Not part of the
 121   // FlashMemory API.
 122   std::span<std::byte> buffer() const { return buffer_; }
 123
 124   bool InjectReadError(const FlashError& error) {
 125     if (read_errors_.full()) {
 126       return false;
 127     }
 128     read_errors_.push_back(error);
 129     return true;
 130   }
 131
 132   bool InjectWriteError(const FlashError& error) {
 133     if (write_errors_.full()) {
 134       return false;
 135     }
 136     write_errors_.push_back(error);
 137     return true;
 138   }
 139
 140  private:
 141   static inline Vector<FlashError, 0> no_errors_;
 142
 143   const std::span<std::byte> buffer_;
 144   Vector<FlashError>& read_errors_;
 145   Vector<FlashError>& write_errors_;
 146 };
 147
 148 // Creates an FakeFlashMemory backed by a std::array. The array is initialized
 149 // to the erased value. A byte array to which to initialize the memory may be
 150 // provided.
 151 template <size_t kSectorSize, size_t kSectorCount, size_t kInjectedErrors = 8>
 152 class FakeFlashMemoryBuffer : public FakeFlashMemory {
 153  public:
 154   // Creates a flash memory with no data written.
 155   explicit FakeFlashMemoryBuffer(
 156       size_t alignment_bytes = kDefaultAlignmentBytes)
 157       : FakeFlashMemoryBuffer(std::array<std::byte, 0>{}, alignment_bytes) {}
 158
 159   // Creates a flash memory initialized to the provided contents.
 160   explicit FakeFlashMemoryBuffer(
 161       std::span<const std::byte> contents,
 162       size_t alignment_bytes = kDefaultAlignmentBytes)
 163       : FakeFlashMemory(buffer_,
 164                         kSectorSize,
 165                         kSectorCount,
 166                         alignment_bytes,
 167                         read_errors_,
 168                         write_errors_) {
 169     std::memset(buffer_.data(), int(kErasedValue), buffer_.size());
 170     std::memcpy(buffer_.data(),
 171                 contents.data(),
 172                 std::min(contents.size(), buffer_.size()));
 173   }
 174
 175  private:
 176   std::array<std::byte, kSectorCount * kSectorSize> buffer_;
 177   Vector<FlashError, kInjectedErrors> read_errors_;
 178   Vector<FlashError, kInjectedErrors> write_errors_;
 179 };
 180
 181 }  // namespace pw::kvs