From dc95e78facc0ff93941f9a9b5243610d7b93b732 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Tue, 3 Sep 2024 20:04:50 +1000 Subject: [PATCH] code-side docs --- quantum/nvm/readme.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 quantum/nvm/readme.md diff --git a/quantum/nvm/readme.md b/quantum/nvm/readme.md new file mode 100644 index 00000000000..0731695e92f --- /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_<>.h + | + ├- eeprom + | ├- nvm_eeconfig.c + | ├- nvm_<>.c + | ╰- ... + | + ├- <> + | ├- nvm_eeconfig.c + | ├- nvm_<>.c + | ╰- ... + ╰- ... +``` + +At the base `nvm` level, for every QMK core system which requires persistence there must be a corresponding `nvm_<>.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_<>.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_<>.c` implementation files which provide the concrete implementation of the upper `nvm_<>.h`. + +New systems requiring persistence can add the corresponding `nvm_<>.h` file, and in most circumstances must also implement equivalent `nvm_<>.c` files for every `nvm` provider. If persistence is not possible for that system, a `nvm_<>.c` file with simple stubs which ignore writes and provide sane defaults must be used instead. \ No newline at end of file