pw_kvs: Expand comment about entry header magic
Change-Id: Ib4d89a42b075442cc96e8a614dfc64e4bf0abdcf
diff --git a/pw_kvs/public/pw_kvs/key_value_store.h b/pw_kvs/public/pw_kvs/key_value_store.h
index 8d31b77..b67de56 100644
--- a/pw_kvs/public/pw_kvs/key_value_store.h
+++ b/pw_kvs/public/pw_kvs/key_value_store.h
@@ -50,7 +50,24 @@
class EntryHeader;
struct EntryHeaderFormat {
- uint32_t magic; // unique identifier
+ // 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;
ChecksumAlgorithm* checksum;
};
