Add EECONFIG_{KB,USER}_DATA_SIZE docs (#26200)

2026-06-03 19:53:31 -03:00 · 2026-05-19 02:58:50 +01:00
parent 1836382f66
commit 0269eea2c9
1 changed files with 114 additions and 6 deletions
@@ -1,14 +1,20 @@
 # Persistent Configuration (EEPROM)

-This allows you to configure persistent settings for your keyboard.  These settings are stored in the EEPROM of your controller, and are retained even after power loss. The settings can be read with `eeconfig_read_kb` and `eeconfig_read_user`, and can be written to using `eeconfig_update_kb` and `eeconfig_update_user`. This is useful for features that you want to be able to toggle (like toggling rgb layer indication).  Additionally, you can use `eeconfig_init_kb` and `eeconfig_init_user` to set the default values for the EEPROM.
-
-The complicated part here, is that there are a bunch of ways that you can store and access data via EEPROM, and there is no "correct" way to do this.  However, you only have a DWORD (4 bytes) for each function.
+This allows you to configure persistent settings for your keyboard.  These settings are stored in the EEPROM of your controller, and are retained even after power loss.

 Keep in mind that EEPROM has a limited number of writes. While this is very high, it's not the only thing writing to the EEPROM, and if you write too often, you can potentially drastically shorten the life of your MCU.

-* If you don't understand the example, then you may want to avoid using this feature, as it is rather complicated.
+::: tip
+If you don't understand the examples, then you may want to avoid using this feature, as it is rather complicated.
+:::

-## Example Implementation
+## Basic
+
+The settings can be read with `eeconfig_read_kb` and `eeconfig_read_user`, and can be written to using `eeconfig_update_kb` and `eeconfig_update_user`. This is useful for features that you want to be able to toggle (like toggling rgb layer indication).  Additionally, you can use `eeconfig_init_kb` and `eeconfig_init_user` to set the default values for the EEPROM.
+
+The complicated part here, is that there are a bunch of ways that you can store and access data via EEPROM, and there is no "correct" way to do this.  However, you only have a DWORD (4 bytes) for each function.
+
+### Example Implementation

 This is an example of how to add settings, and read and write it. We're using the user keymap for the example here.  This is a complex function, and has a lot going on.  In fact, it uses a lot of the above functions to work!

@@ -126,9 +132,111 @@ void eeconfig_init_user(void) {  // EEPROM is getting reset!

 And you're done.  The RGB layer indication will only work if you want it to. And it will be saved, even after unplugging the board. And if you use any of the RGB codes, it will disable the layer indication, so that it stays on the mode and color that you set it to.

-## 'EECONFIG' Function Documentation
+### Basic API

 * Keyboard/Revision: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` and `void eeconfig_update_kb(uint32_t val)`
 * Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`

 The `val` is the value of the data that you want to write to EEPROM.  And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM.
+
+## Datablock {#datablock}
+
+An extended form exists that allows larger blocks of data to be allocated.
+
+::: info
+When using datablock, the [basic API](#eeconfig-function-documentation) is unavailable.
+:::
+
+:::::tabs
+
+==== keyboard
+
+In `config.h`, define the size required, and optionally a version number:
+
+| Define                       | Default                   | Description                                                      |
+|------------------------------|---------------------------|------------------------------------------------------------------|
+| `EECONFIG_KB_DATA_SIZE`      | `0`                       | Size in bytes for the persistent block of data                   |
+| `EECONFIG_KB_DATA_VERSION`   | `EECONFIG_KB_DATA_SIZE`   | Version number that can be incremented to invalidate stored data |
+
+Which exposes the following API:
+
+```c
+bool     eeconfig_is_kb_datablock_valid(void);
+uint32_t eeconfig_read_kb_datablock(void *data, uint32_t offset, uint32_t length) __attribute__((nonnull));
+uint32_t eeconfig_update_kb_datablock(const void *data, uint32_t offset, uint32_t length) __attribute__((nonnull));
+void     eeconfig_init_kb_datablock(void);
+#    define eeconfig_read_kb_datablock_field(__object, __field) eeconfig_read_kb_datablock(&(__object.__field), offsetof(typeof(__object), __field), sizeof(__object.__field))
+#    define eeconfig_update_kb_datablock_field(__object, __field) eeconfig_update_kb_datablock(&(__object.__field), offsetof(typeof(__object), __field), sizeof(__object.__field))
+```
+
+==== keymap
+
+In `config.h`, define the size required, and optionally a version number:
+
+| Define                       | Default                   | Description                                                      |
+|------------------------------|---------------------------|------------------------------------------------------------------|
+| `EECONFIG_USER_DATA_SIZE`    | `0`                       | Size in bytes for the persistent block of data                   |
+| `EECONFIG_USER_DATA_VERSION` | `EECONFIG_USER_DATA_SIZE` | Version number that can be incremented to invalidate stored data |
+
+Which exposes the following API:
+
+```c
+bool     eeconfig_is_user_datablock_valid(void);
+uint32_t eeconfig_read_user_datablock(void *data, uint32_t offset, uint32_t length) __attribute__((nonnull));
+uint32_t eeconfig_update_user_datablock(const void *data, uint32_t offset, uint32_t length) __attribute__((nonnull));
+void     eeconfig_init_user_datablock(void);
+#    define eeconfig_read_user_datablock_field(__object, __field) eeconfig_read_user_datablock(&(__object.__field), offsetof(typeof(__object), __field), sizeof(__object.__field))
+#    define eeconfig_update_user_datablock_field(__object, __field) eeconfig_update_user_datablock(&(__object.__field), offsetof(typeof(__object), __field), sizeof(__object.__field))
+```
+
+:::::
+
+### Example
+
+This is an example of how to add settings, and read and write it. We're using the user keymap for the example here.
+
+In your `config.h` add:
+
+```c
+#define EECONFIG_USER_DATA_SIZE 8
+```
+
+In your keymap.c file, add:
+
+```c
+#include "debug.h"
+#include "timer.h"
+#include "eeconfig.h"
+
+typedef struct my_config_t {
+    uint64_t data;
+} my_config_t;
+
+static my_config_t config;
+
+void keyboard_post_init_user(void) {
+    if (!eeconfig_is_user_datablock_valid()) {
+        eeconfig_init_user_datablock();
+    }
+
+    eeconfig_read_user_datablock(&config, 0, sizeof(my_config_t));
+}
+
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    if (!record->event.pressed) {
+        config.data += 1;
+        eeconfig_update_user_datablock(&config, 0, sizeof(my_config_t));
+    }
+
+    return true;
+}
+
+void housekeeping_task_user(void) {
+    static uint32_t last_sync = 0;
+    if (timer_elapsed32(last_sync) > 1000) {
+        last_sync = timer_read32();
+
+        dprintf("Config: %ld\n", config.data);
+    }
+}
+```