2020-01-31 01:32:18 +00:00
|
|
|
// Copyright 2020 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.
|
2020-02-04 15:36:45 +00:00
|
|
|
|
|
|
|
// This file defines classes for managing the in-flash format for KVS entires.
|
2020-01-31 01:32:18 +00:00
|
|
|
#pragma once
|
|
|
|
|
|
|
|
#include <cstddef>
|
|
|
|
#include <cstdint>
|
|
|
|
#include <cstring>
|
2020-02-04 15:36:45 +00:00
|
|
|
#include <string_view>
|
2020-01-31 01:32:18 +00:00
|
|
|
|
2020-02-12 00:45:02 +00:00
|
|
|
#include "pw_kvs/alignment.h"
|
2020-02-04 15:36:45 +00:00
|
|
|
#include "pw_kvs/checksum.h"
|
|
|
|
#include "pw_kvs/flash_memory.h"
|
2020-01-31 01:32:18 +00:00
|
|
|
#include "pw_span/span.h"
|
|
|
|
|
|
|
|
namespace pw::kvs {
|
|
|
|
|
2020-02-12 19:26:05 +00:00
|
|
|
// Disk format of the header used for each key-value entry.
|
|
|
|
struct EntryHeader {
|
|
|
|
uint32_t magic;
|
|
|
|
|
|
|
|
// The checksum of the entire entry, including the header, key, value, and
|
|
|
|
// zero-value padding bytes. The checksum is calculated as if the checksum
|
|
|
|
// field value was zero.
|
|
|
|
uint32_t checksum;
|
|
|
|
|
|
|
|
// Stores the alignment in 16-byte units, starting from 16. To calculate the
|
|
|
|
// number of bytes, add one to this number and multiply by 16.
|
|
|
|
uint8_t alignment_units;
|
|
|
|
|
|
|
|
// The length of the key in bytes. The key is not null terminated.
|
|
|
|
// 6 bits, 0:5 - key length - maximum 64 characters
|
|
|
|
// 2 bits, 6:7 - reserved
|
|
|
|
uint8_t key_length_bytes;
|
|
|
|
|
|
|
|
// Byte length of the value; maximum of 65534. The max uint16_t value (65535
|
|
|
|
// or 0xFFFF) is reserved to indicate this is a tombstone (deleted) entry.
|
|
|
|
uint16_t value_length_bytes;
|
|
|
|
|
|
|
|
// The version of the key. Monotonically increasing.
|
|
|
|
uint32_t key_version;
|
|
|
|
};
|
|
|
|
|
|
|
|
static_assert(sizeof(EntryHeader) == 16, "EntryHeader must not have padding");
|
|
|
|
|
|
|
|
// Entry represents a key-value entry.
|
|
|
|
class Entry {
|
2020-02-04 15:36:45 +00:00
|
|
|
public:
|
2020-02-12 19:26:05 +00:00
|
|
|
static constexpr size_t kMinAlignmentBytes = sizeof(EntryHeader);
|
|
|
|
|
|
|
|
Entry() = default;
|
|
|
|
|
|
|
|
// Creates a new Entry for a valid (non-deleted) entry.
|
|
|
|
static Entry Valid(uint32_t magic,
|
|
|
|
ChecksumAlgorithm* algorithm,
|
|
|
|
std::string_view key,
|
|
|
|
span<const std::byte> value,
|
|
|
|
size_t alignment_bytes,
|
|
|
|
uint32_t key_version) {
|
|
|
|
return Entry(magic,
|
|
|
|
algorithm,
|
|
|
|
key,
|
|
|
|
value,
|
|
|
|
value.size(),
|
|
|
|
alignment_bytes,
|
|
|
|
key_version);
|
2020-02-05 23:30:49 +00:00
|
|
|
}
|
|
|
|
|
2020-02-12 19:26:05 +00:00
|
|
|
// Creates a new Entry for a tombstone entry, which marks a deleted key.
|
|
|
|
static Entry Tombstone(uint32_t magic,
|
|
|
|
ChecksumAlgorithm* algorithm,
|
|
|
|
std::string_view key,
|
|
|
|
size_t alignment_bytes,
|
|
|
|
uint32_t key_version) {
|
|
|
|
return Entry(magic,
|
|
|
|
algorithm,
|
|
|
|
key,
|
|
|
|
{},
|
|
|
|
kDeletedValueLength,
|
|
|
|
alignment_bytes,
|
|
|
|
key_version);
|
2020-02-05 23:30:49 +00:00
|
|
|
}
|
2020-01-31 01:32:18 +00:00
|
|
|
|
2020-02-04 15:36:45 +00:00
|
|
|
Status VerifyChecksum(ChecksumAlgorithm* algorithm,
|
|
|
|
std::string_view key,
|
|
|
|
span<const std::byte> value) const;
|
|
|
|
|
|
|
|
Status VerifyChecksumInFlash(FlashPartition* partition,
|
|
|
|
FlashPartition::Address header_address,
|
2020-02-05 01:47:40 +00:00
|
|
|
ChecksumAlgorithm* algorithm) const;
|
2020-01-31 01:32:18 +00:00
|
|
|
|
2020-02-06 23:55:45 +00:00
|
|
|
// Calculates the total size of an entry, including padding.
|
|
|
|
static constexpr size_t size(size_t alignment_bytes,
|
|
|
|
std::string_view key,
|
2020-02-05 17:01:18 +00:00
|
|
|
span<const std::byte> value) {
|
2020-02-06 23:55:45 +00:00
|
|
|
return AlignUp(sizeof(EntryHeader) + key.size() + value.size(),
|
|
|
|
alignment_bytes);
|
2020-02-05 17:01:18 +00:00
|
|
|
}
|
|
|
|
|
2020-02-06 23:55:45 +00:00
|
|
|
// Total size of this entry, including padding.
|
|
|
|
size_t size() const { return AlignUp(content_size(), alignment_bytes()); }
|
2020-02-02 21:58:19 +00:00
|
|
|
|
2020-02-12 19:26:05 +00:00
|
|
|
uint32_t magic() const { return header_.magic; }
|
2020-02-02 21:58:19 +00:00
|
|
|
|
2020-02-12 19:26:05 +00:00
|
|
|
uint32_t checksum() const { return header_.checksum; }
|
2020-02-02 21:58:19 +00:00
|
|
|
|
2020-02-06 23:55:45 +00:00
|
|
|
// The length of the key in bytes. Keys are not null terminated.
|
2020-02-12 19:26:05 +00:00
|
|
|
size_t key_length() const { return header_.key_length_bytes; }
|
2020-02-05 23:30:49 +00:00
|
|
|
|
2020-02-06 23:55:45 +00:00
|
|
|
static constexpr size_t max_key_length() { return kKeyLengthMask; }
|
2020-02-02 21:58:19 +00:00
|
|
|
|
2020-02-06 23:55:45 +00:00
|
|
|
// The length of the value, which is 0 if this is a tombstone entry.
|
2020-02-12 19:26:05 +00:00
|
|
|
size_t value_length() const {
|
|
|
|
return deleted() ? 0u : header_.value_length_bytes;
|
|
|
|
}
|
2020-02-06 23:55:45 +00:00
|
|
|
|
|
|
|
static constexpr size_t max_value_length() { return 0xFFFE; }
|
|
|
|
|
2020-02-12 19:26:05 +00:00
|
|
|
size_t alignment_bytes() const { return (header_.alignment_units + 1) * 16; }
|
2020-02-06 23:55:45 +00:00
|
|
|
|
2020-02-12 19:26:05 +00:00
|
|
|
uint32_t key_version() const { return header_.key_version; }
|
2020-01-31 01:32:18 +00:00
|
|
|
|
2020-02-06 23:55:45 +00:00
|
|
|
// True if this is a tombstone entry.
|
2020-02-12 19:26:05 +00:00
|
|
|
bool deleted() const {
|
|
|
|
return header_.value_length_bytes == kDeletedValueLength;
|
|
|
|
}
|
2020-02-06 23:55:45 +00:00
|
|
|
|
2020-01-31 01:32:18 +00:00
|
|
|
private:
|
2020-02-06 23:55:45 +00:00
|
|
|
// The total size of the entry, excluding padding.
|
|
|
|
size_t content_size() const {
|
|
|
|
return sizeof(EntryHeader) + key_length() + value_length();
|
|
|
|
}
|
|
|
|
|
2020-01-31 01:32:18 +00:00
|
|
|
static constexpr uint32_t kKeyLengthMask = 0b111111;
|
2020-02-06 23:55:45 +00:00
|
|
|
static constexpr uint16_t kDeletedValueLength = 0xFFFF;
|
2020-02-05 23:30:49 +00:00
|
|
|
|
2020-02-12 19:26:05 +00:00
|
|
|
Entry(uint32_t magic,
|
|
|
|
ChecksumAlgorithm* algorithm,
|
|
|
|
std::string_view key,
|
|
|
|
span<const std::byte> value,
|
|
|
|
uint16_t value_length_bytes,
|
|
|
|
size_t alignment_bytes,
|
|
|
|
uint32_t key_version);
|
2020-01-31 01:32:18 +00:00
|
|
|
|
2020-02-04 15:36:45 +00:00
|
|
|
span<const std::byte> checksum_bytes() const {
|
2020-02-12 19:26:05 +00:00
|
|
|
return as_bytes(span(&header_.checksum, 1));
|
2020-02-04 15:36:45 +00:00
|
|
|
}
|
|
|
|
|
2020-02-12 22:49:14 +00:00
|
|
|
span<const std::byte> CalculateChecksum(ChecksumAlgorithm* algorithm,
|
|
|
|
std::string_view key,
|
|
|
|
span<const std::byte> value) const;
|
2020-02-04 15:36:45 +00:00
|
|
|
|
2020-02-06 23:55:45 +00:00
|
|
|
static constexpr uint8_t alignment_bytes_to_units(size_t alignment_bytes) {
|
|
|
|
return (alignment_bytes + 15) / 16 - 1; // An alignment of 0 is invalid.
|
|
|
|
}
|
|
|
|
|
2020-02-12 19:26:05 +00:00
|
|
|
EntryHeader header_;
|
2020-01-31 01:32:18 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
} // namespace pw::kvs
|