blob: 3f1d4e9c2fac0587a87575ff8d7234ce7cffbc49 [file] [log] [blame]
// 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 <span>
#include <type_traits>
#include <utility>
#include "pw_bytes/span.h"
#include "pw_checksum/crc16_ccitt.h"
#include "pw_preprocessor/compiler.h"
#include "pw_status/status.h"
#include "pw_stream/stream.h"
namespace pw::persistent_ram {
// A PersistentBufferWriter implements the pw::stream::Writer interface and
// provides handles to mutate and access the underlying data of a
// PersistentBuffer. This object should NOT be stored in persistent RAM.
//
// Only one writer should be open at a given time.
class PersistentBufferWriter : public stream::Writer {
public:
PersistentBufferWriter() = delete;
size_t ConservativeWriteLimit() const override {
return buffer_.size_bytes() - size_;
}
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;
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");
// When a PersistentBuffer is statically allocated in persistent memory, its
// state will persist across soft resets in accordance with the expected
// behavior of the underlying RAM. This object is completely safe to use before
// static constructors are called as its constructor is effectively a no-op.
//
// While the stored data can be read by PersistentBuffer's public functions,
// each public function must validate the integrity of the stored data. It's
// typically more performant to get a handle to a PersistentBufferWriter
// instead, as data is validated on creation of the PersistentBufferWriter,
// which allows access to the underlying data without needing to validate the
// data's integrity with each call to PersistentBufferWriter functions.
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