1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
// 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.
#pragma once
#include <cstdint>
#include <span>
#include "pw_kvs/checksum.h"
namespace pw {
namespace kvs {
struct EntryFormat;
namespace internal {
// Disk format of the header used for each key-value entry.
struct EntryHeader {
// For KVS magic value always use a random 32 bit integer rather than a
// human readable 4 bytes. See pw_kvs/format.h::EntryFormat for more
// information.
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_size_bytes;
// The transaction ID for this key. Monotonically increasing.
uint32_t transaction_id;
};
static_assert(sizeof(EntryHeader) == 16, "EntryHeader must not have padding");
// This class wraps EntryFormat instances to support having multiple
// simultaneously supported formats.
class EntryFormats {
public:
explicit constexpr EntryFormats(std::span<const EntryFormat> formats)
: formats_(formats) {}
explicit constexpr EntryFormats(const EntryFormat& format)
: formats_(&format, 1) {}
const EntryFormat& primary() const { return formats_.front(); }
bool KnownMagic(uint32_t magic) const { return Find(magic) != nullptr; }
const EntryFormat* Find(uint32_t magic) const;
private:
const std::span<const EntryFormat> formats_;
};
} // namespace internal
// The EntryFormat defines properties of KVS entries that use a particular magic
// number.
struct EntryFormat {
// Magic is a unique constant identifier for entries.
//
// Upon reading from an address in flash, the magic number facilitiates
// quickly differentiating between:
//
// - Reading erased data - typically 0xFF - from flash.
// - Reading corrupted data
// - Reading a valid entry
//
// When selecting a magic for your particular KVS, pick a random 32 bit
// integer rather than a human readable 4 bytes. This decreases the
// probability of a collision with a real string when scanning in the case of
// corruption. To generate such a number:
/*
$ python3 -c 'import random; print(hex(random.randint(0,2**32)))'
0xaf741757
*/
uint32_t magic;
// The checksum algorithm is used to calculate checksums for KVS entries. If
// it is null, no checksum is used.
ChecksumAlgorithm* checksum;
};
} // namespace kvs
} // namespace pw
|
