aboutsummaryrefslogtreecommitdiff
path: root/docs/eeprom_driver.md
diff options
context:
space:
mode:
authorNick Brassel <[email protected]>2024-05-30 12:00:41 +1000
committerGitHub <[email protected]>2024-05-30 12:00:41 +1000
commit6ef97172889ccd5db376b2a9f8825489e24fdac4 (patch)
tree334e3bf41c8554d4bee73a140822f95f60eb64e9 /docs/eeprom_driver.md
parent395766657ff98a4b1fd0dcba5917557f8acbb9e4 (diff)
downloadqmk_firmware-6ef97172889ccd5db376b2a9f8825489e24fdac4.tar.gz
qmk_firmware-6ef97172889ccd5db376b2a9f8825489e24fdac4.zip
Vitepress conversion of docs. (#23795)
Diffstat (limited to 'docs/eeprom_driver.md')
-rw-r--r--docs/eeprom_driver.md50
1 files changed, 31 insertions, 19 deletions
diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md
index c77d18c68d..6d13377ed8 100644
--- a/docs/eeprom_driver.md
+++ b/docs/eeprom_driver.md
@@ -1,4 +1,4 @@
-# EEPROM Driver Configuration :id=eeprom-driver-configuration
+# EEPROM Driver Configuration {#eeprom-driver-configuration}
The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
@@ -12,17 +12,19 @@ Driver | Description
`EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
`EEPROM_DRIVER = wear_leveling` | Frontend driver for the wear_leveling system, allowing for EEPROM emulation on top of flash -- both in-MCU and external SPI NOR flash.
-## Vendor Driver Configuration :id=vendor-eeprom-driver-configuration
+## Vendor Driver Configuration {#vendor-eeprom-driver-configuration}
-#### STM32 L0/L1 Configuration :id=stm32l0l1-eeprom-driver-configuration
+#### STM32 L0/L1 Configuration {#stm32l0l1-eeprom-driver-configuration}
-!> Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.
+::: warning
+Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.
+:::
`config.h` override | Description | Default Value
------------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------
`#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled.
-## I2C Driver Configuration :id=i2c-eeprom-driver-configuration
+## I2C Driver Configuration {#i2c-eeprom-driver-configuration}
Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h:
@@ -52,9 +54,11 @@ RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C` | <https://www.sparkfun.com/p
24LC256 EEPROM | `#define EEPROM_I2C_24LC256` | <https://www.sparkfun.com/products/525>
MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895>
-?> If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
+::: tip
+If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
+:::
-## SPI Driver Configuration :id=spi-eeprom-driver-configuration
+## SPI Driver Configuration {#spi-eeprom-driver-configuration}
Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h:
@@ -74,9 +78,11 @@ Module | Equivalent `#define` | Source
-----------------|---------------------------------|------------------------------------------
MB85RS64V FRAM | `define EEPROM_SPI_MB85RS64V` | <https://www.adafruit.com/product/1897>
-!> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
+::: warning
+There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
+:::
-## Transient Driver configuration :id=transient-eeprom-driver-configuration
+## Transient Driver configuration {#transient-eeprom-driver-configuration}
The only configurable item for the transient EEPROM driver is its size:
@@ -86,13 +92,13 @@ The only configurable item for the transient EEPROM driver is its size:
Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`.
-## Wear-leveling Driver Configuration :id=wear_leveling-eeprom-driver-configuration
+## Wear-leveling Driver Configuration {#wear_leveling-eeprom-driver-configuration}
The wear-leveling driver uses an algorithm to minimise the number of erase cycles on the underlying MCU flash memory.
There is no specific configuration for this driver, but the wear-leveling system used by this driver may need configuration. See the [wear-leveling configuration](#wear_leveling-configuration) section for more information.
-# Wear-leveling Configuration :id=wear_leveling-configuration
+# Wear-leveling Configuration {#wear_leveling-configuration}
The wear-leveling driver has a few possible _backing stores_ that may be used by adding to your keyboard's `rules.mk` file:
@@ -103,9 +109,11 @@ Driver | Description
`WEAR_LEVELING_DRIVER = rp2040_flash` | This driver is used to write to the same storage the RP2040 executes code from.
`WEAR_LEVELING_DRIVER = legacy` | This driver is the "legacy" emulated EEPROM provided in historical revisions of QMK. Currently used for STM32F0xx and STM32F4x1, but slated for deprecation and removal once `embedded_flash` support for those MCU families is complete.
-!> All wear-leveling drivers require an amount of RAM equivalent to the selected logical EEPROM size. Increasing the size to 32kB of EEPROM requires 32kB of RAM, which a significant number of MCUs simply do not have.
+::: warning
+All wear-leveling drivers require an amount of RAM equivalent to the selected logical EEPROM size. Increasing the size to 32kB of EEPROM requires 32kB of RAM, which a significant number of MCUs simply do not have.
+:::
-## Wear-leveling Embedded Flash Driver Configuration :id=wear_leveling-efl-driver-configuration
+## Wear-leveling Embedded Flash Driver Configuration {#wear_leveling-efl-driver-configuration}
This driver performs writes to the embedded flash storage embedded in the MCU. In most circumstances, the last few of sectors of flash are used in order to minimise the likelihood of collision with program code.
@@ -119,11 +127,13 @@ Configurable options in your keyboard's `config.h`:
`#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
`#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly.
-!> If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding.
+::: warning
+If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding.
+:::
-## Wear-leveling SPI Flash Driver Configuration :id=wear_leveling-flash_spi-driver-configuration
+## Wear-leveling SPI Flash Driver Configuration {#wear_leveling-flash_spi-driver-configuration}
-This driver performs writes to an external SPI NOR Flash peripheral. It also requires a working configuration for the SPI NOR Flash peripheral -- see the [flash driver](flash_driver.md) documentation for more information.
+This driver performs writes to an external SPI NOR Flash peripheral. It also requires a working configuration for the SPI NOR Flash peripheral -- see the [flash driver](flash_driver) documentation for more information.
Configurable options in your keyboard's `config.h`:
@@ -135,9 +145,11 @@ Configurable options in your keyboard's `config.h`:
`#define WEAR_LEVELING_BACKING_SIZE` | `(block_count*block_size)` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
`#define BACKING_STORE_WRITE_SIZE` | `8` | The write width used whenever a write is performed on the external flash peripheral.
-!> There is currently a limit of 64kB for the EEPROM subsystem within QMK, so using a larger flash is not going to be beneficial as the logical size cannot be increased beyond 65536. The backing size may be increased to a larger value, but erase timing may suffer as a result.
+::: warning
+There is currently a limit of 64kB for the EEPROM subsystem within QMK, so using a larger flash is not going to be beneficial as the logical size cannot be increased beyond 65536. The backing size may be increased to a larger value, but erase timing may suffer as a result.
+:::
-## Wear-leveling RP2040 Driver Configuration :id=wear_leveling-rp2040-driver-configuration
+## Wear-leveling RP2040 Driver Configuration {#wear_leveling-rp2040-driver-configuration}
This driver performs writes to the same underlying storage that the RP2040 executes its code.
@@ -151,7 +163,7 @@ Configurable options in your keyboard's `config.h`:
`#define WEAR_LEVELING_BACKING_SIZE` | `8192` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size as well as the sector size.
`#define BACKING_STORE_WRITE_SIZE` | `2` | The write width used whenever a write is performed on the external flash peripheral.
-## Wear-leveling Legacy EEPROM Emulation Driver Configuration :id=wear_leveling-legacy-driver-configuration
+## Wear-leveling Legacy EEPROM Emulation Driver Configuration {#wear_leveling-legacy-driver-configuration}
This driver performs writes to the embedded flash storage embedded in the MCU much like the normal Embedded Flash Driver, and is only for use with STM32F0xx and STM32F4x1 devices. This flash implementation is still currently provided as the EFL driver is currently non-functional for the previously mentioned families.