From 191d89bb76b3060f57d999599f97b5b9da522180 Mon Sep 17 00:00:00 2001
From: sys64738 <sys64738@noreply.example.org>
Date: Thu, 26 Aug 2021 18:56:24 +0000
Subject: [PATCH] Add 'Persistent storage'

---
 Persistent-storage.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 Persistent-storage.md

diff --git a/Persistent-storage.md b/Persistent-storage.md
new file mode 100644
index 0000000..7ad2c22
--- /dev/null
+++ b/Persistent-storage.md
@@ -0,0 +1,43 @@
+Persistent storage data is saved to the on-chip/on-board flash, if available. On the Pico, this is the (usually 2 MiB) XIP/QSPI flash.
+
+### Storage structure
+
+A header resides in the last 256 bytes of flash, with the following structure:
+
+```
+               3            7            b            f
+ --+----------------------------------------------------+
+ 0 | f0 9f 8f b3  ef b8 8f e2  80 8d e2 9a  a7 ef b8 8f |
+10 | fwver mm nm  <reserved (0xff)       >  <tbl djb2>  |
+20 | <mode data table ...>                              |
+30 |                                                    |
+.. |                                                    |
+e0 | <reserved (0xff) ...>                              |
+ --+----------------------------------------------------+
+```
+ 
+Reserved space is filled with 0xff-bytes.
+
+The first 16 bytes are filled with a fixed 'magic' value. Then the following values appear:
+* `fwver`: firmware/storage structure version: 2 bytes, currently 0x0010
+* `mm`: current mode: 1 byte
+* `nm`: number of modes: 1 byte, equal to the number of elements in the "mode data table" array
+* `tbl djb2`: DJB2 hash of the entire mode data table (including unused ones, cf. `nm`)
+
+After this data, the "mode data table" follows, consisting of 16 entries of 12 bytes each, specifying where the data of each mode resides in flash. It has the following structure:
+
+```c
+struct mode_data {
+    uint16_t version;
+    uint16_t datasize;
+    uint28_t flashoffset; // from beginning of flash
+    uint4_t modeid;
+    uint32_t data_djb2;
+};
+```
+
+The `flashoffset` is relative to the beginning of flash. `version` is the version of the mode. `modeid` is encoded by extending `flashoffset` to 32 bits, and encodign `modeid` in the most-significant nybble. `data_djb2` is the DJB2 hash of the on-flash data.
+
+Mode data blocks are allocated from the start of the last flash page (which is implementation defined), filling it up, and then continuing to the block before. First, smaller mode data blocks are allocated, ending with the larger ones.
+
+### Storage API
\ No newline at end of file