aboutsummaryrefslogtreecommitdiff
path: root/quantum/nvm/readme.md
diff options
context:
space:
mode:
authorNick Brassel <[email protected]>2025-03-21 23:38:34 +1100
committerGitHub <[email protected]>2025-03-21 23:38:34 +1100
commit2b00b846dce1d1267dfdb2a3c2972a367cc0dd44 (patch)
tree6d801a8d83c58ee646b789bfa9ab912857ee7d8c /quantum/nvm/readme.md
parentc9d62ddc78e879053241202b288d0129073b07dc (diff)
downloadqmk_firmware-2b00b846dce1d1267dfdb2a3c2972a367cc0dd44.tar.gz
qmk_firmware-2b00b846dce1d1267dfdb2a3c2972a367cc0dd44.zip
Non-volatile memory data repository pattern (#24356)
* First batch of eeconfig conversions. * Offset and length for datablocks. * `via`, `dynamic_keymap`. * Fix filename. * Commentary. * wilba leds * satisfaction75 * satisfaction75 * more keyboard whack-a-mole * satisfaction75 * omnikeyish * more whack-a-mole * `generic_features.mk` to automatically pick up nvm repositories * thievery * deferred variable resolve * whitespace * convert api to structs/unions * convert api to structs/unions * convert api to structs/unions * fixups * code-side docs * code size fix * rollback * nvm_xxxxx_erase * Updated location of eeconfig magic numbers so non-EEPROM nvm drivers can use them too. * Fixup build. * Fixup compilation error with encoders. * Build fixes. * Add `via_ci` keymap to onekey to exercise VIA bindings (and thus dynamic keymap et.al.), fixup compilation errors based on preprocessor+sizeof. * Build failure rectification.
Diffstat (limited to 'quantum/nvm/readme.md')
-rw-r--r--quantum/nvm/readme.md30
1 files changed, 30 insertions, 0 deletions
diff --git a/quantum/nvm/readme.md b/quantum/nvm/readme.md
new file mode 100644
index 0000000000..0731695e92
--- /dev/null
+++ b/quantum/nvm/readme.md
@@ -0,0 +1,30 @@
+# Non-volatile Memory - Data Repositories
+
+This area is intentionally structured in the following way:
+
+```
+╰- quantum
+ ╰- nvm
+ ├- readme.md
+ ├- rules.mk
+ |
+ ├- nvm_eeconfig.h
+ ├- nvm_<<system>>.h
+ |
+ ├- eeprom
+ | ├- nvm_eeconfig.c
+ | ├- nvm_<<system>>.c
+ | ╰- ...
+ |
+ ├- <<another provider>>
+ | ├- nvm_eeconfig.c
+ | ├- nvm_<<system>>.c
+ | ╰- ...
+ ╰- ...
+```
+
+At the base `nvm` level, for every QMK core system which requires persistence there must be a corresponding `nvm_<<system>>.h` header file. This provides the data repository API to the "owner" system, and allows the underlying data persistence mechanism to be abstracted away from upper code. Any conversion to/from a `.raw` field should occur inside the `nvm_<<system>>.c` layer, with the API using values, such as structs or unions exposed to the rest of QMK.
+
+Each `nvm` "provider" is a corresponding child directory consisting of its name, such as `eeprom`, and corresponding `nvm_<<system>>.c` implementation files which provide the concrete implementation of the upper `nvm_<<system>>.h`.
+
+New systems requiring persistence can add the corresponding `nvm_<<system>>.h` file, and in most circumstances must also implement equivalent `nvm_<<system>>.c` files for every `nvm` provider. If persistence is not possible for that system, a `nvm_<<system>>.c` file with simple stubs which ignore writes and provide sane defaults must be used instead. \ No newline at end of file