persistent_buffer.h

// Copyright 2021 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
#pragma once
 
#include <cstdint>
#include <cstring>
#include <type_traits>
#include <utility>
 
#include "pw_bytes/span.h"
#include "pw_checksum/crc16_ccitt.h"
#include "pw_preprocessor/compiler.h"
#include "pw_span/span.h"
#include "pw_status/status.h"
#include "pw_stream/stream.h"
 
namespace pw::persistent_ram {
 
 
class PersistentBufferWriter : public stream::NonSeekableWriter {
 public:
  PersistentBufferWriter() = delete;
 
 private:
  template <size_t>
  friend class PersistentBuffer;
 
  PersistentBufferWriter(ByteSpan buffer,
                         volatile size_t& size,
                         volatile uint16_t& checksum)
      : buffer_(buffer), size_(size), checksum_(checksum) {}
 
  // Implementation for writing data to this stream.
  Status DoWrite(ConstByteSpan data) override;
 
  size_t ConservativeLimit(LimitType limit) const override {
    if (limit == LimitType::kWrite) {
      return buffer_.size_bytes() - size_;
    }
    return 0;
  }
 
  ByteSpan buffer_;
  volatile size_t& size_;
  volatile uint16_t& checksum_;
};
 
// The PersistentBuffer class intentionally uses uninitialized memory, which
// triggers compiler warnings. Disable those warnings for this file.
PW_MODIFY_DIAGNOSTICS_PUSH();
PW_MODIFY_DIAGNOSTIC(ignored, "-Wuninitialized");
PW_MODIFY_DIAGNOSTIC_GCC(ignored, "-Wmaybe-uninitialized");
 
template <size_t kMaxSizeBytes>
class PersistentBuffer {
 public:
  // The default constructor intentionally does not initialize anything. This
  // allows a persistent buffer statically allocated in persistent RAM to be
  // highly available.
  //
  // Explicitly declaring an empty constructor rather than using the default
  // constructor prevents the object from being zero-initialized when the object
  // is value initialized. If this was left as a default constructor,
  // PersistentBuffer objects declared as value-initialized would be
  // zero-initialized.
  //
  //   // Value initialization:
  //   PersistentBuffer<256> persistent_buffer();
  //
  //   // Default initialization:
  //   PersistentBuffer<256> persistent_buffer;
  PersistentBuffer() {}
  // Disable copy and move constructors.
  PersistentBuffer(const PersistentBuffer&) = delete;
  PersistentBuffer(PersistentBuffer&&) = delete;
  // Explicit no-op destructor.
  ~PersistentBuffer() {}
 
  PersistentBufferWriter GetWriter() {
    if (!has_value()) {
      clear();
    }
    return PersistentBufferWriter(
        ByteSpan(const_cast<std::byte*>(buffer_), kMaxSizeBytes),
        size_,
        checksum_);
  }
 
  size_t size() const {
    if (has_value()) {
      return size_;
    }
    return 0;
  }
 
  const std::byte* data() const { return const_cast<std::byte*>(buffer_); }
 
  void clear() {
    size_ = 0;
    checksum_ = checksum::Crc16Ccitt::kInitialValue;
  }
 
  bool has_value() const {
    if (size_ > kMaxSizeBytes || size_ == 0) {
      return false;
    }
 
    // Check checksum. This is more costly.
    return checksum_ == checksum::Crc16Ccitt::Calculate(ConstByteSpan(
                            const_cast<std::byte*>(buffer_), size_));
  }
 
 private:
  // None of these members are initialized by the constructor by design.
  volatile uint16_t checksum_;
  volatile size_t size_;
  volatile std::byte buffer_[kMaxSizeBytes];
};
 
PW_MODIFY_DIAGNOSTICS_POP();
 
}  // namespace pw::persistent_ram