diff options
Diffstat (limited to 'docs')
45 files changed, 1670 insertions, 725 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index b60eb1b23d..2c9a81eca0 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -83,14 +83,13 @@ * [Key Overrides](feature_key_overrides.md) * [Layers](feature_layers.md) * [One Shot Keys](one_shot_keys.md) - * [Pointing Device](feature_pointing_device.md) * [Raw HID](feature_rawhid.md) * [Secure](feature_secure.md) + * [Send String](feature_send_string.md) * [Sequencer](feature_sequencer.md) * [Swap Hands](feature_swap_hands.md) * [Tap Dance](feature_tap_dance.md) * [Tap-Hold Configuration](tap_hold.md) - * [Terminal](feature_terminal.md) * [Unicode](feature_unicode.md) * [Userspace](feature_userspace.md) * [WPM Calculation](feature_wpm.md) @@ -109,6 +108,7 @@ * [Audio](feature_audio.md) * [Bluetooth](feature_bluetooth.md) * [Bootmagic Lite](feature_bootmagic.md) + * [Converters](feature_converters.md) * [Custom Matrix](custom_matrix.md) * [Digitizer](feature_digitizer.md) * [DIP Switch](feature_dip_switch.md) @@ -117,7 +117,7 @@ * [Joystick](feature_joystick.md) * [LED Indicators](feature_led_indicators.md) * [MIDI](feature_midi.md) - * [Proton C Conversion](proton_c_conversion.md) + * [Pointing Device](feature_pointing_device.md) * [PS/2 Mouse](feature_ps2_mouse.md) * [Split Keyboard](feature_split_keyboard.md) * [Stenography](feature_stenography.md) @@ -149,6 +149,7 @@ * [SPI Driver](spi_driver.md) * [WS2812 Driver](ws2812_driver.md) * [EEPROM Driver](eeprom_driver.md) + * [Flash Driver](flash_driver.md) * ['serial' Driver](serial_driver.md) * [UART Driver](uart_driver.md) * [GPIO Controls](gpio_control.md) @@ -167,6 +168,8 @@ * Arm/ChibiOS * [Selecting an MCU](platformdev_selecting_arm_mcu.md) * [Early initialization](platformdev_chibios_earlyinit.md) + * [Raspberry Pi RP2040](platformdev_rp2040.md) + * [Proton C](platformdev_proton_c.md) * [WeAct Blackpill F411](platformdev_blackpill_f411.md) * QMK Reference diff --git a/docs/cli_commands.md b/docs/cli_commands.md index a380d3eb2f..4608ed85b6 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -90,6 +90,8 @@ This command is similar to `qmk compile`, but can also target a bootloader. The This command is directory aware. It will automatically fill in KEYBOARD and/or KEYMAP if you are in a keyboard or keymap directory. +This command can also flash binary firmware files (hex or bin) such as the ones produced by [Configurator](https://config.qmk.fm). + **Usage for Configurator Exports**: ``` @@ -102,6 +104,21 @@ qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configurat qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] ``` +**Usage for pre-compiled firmwares**: + +**Note**: The microcontroller needs to be specified (`-m` argument) for keyboards with the following bootloaders: +* HalfKay +* QMK HID +* USBaspLoader + +ISP flashing is also supported with the following flashers and require the microcontroller to be specified: +* USBasp +* USBtinyISP + +``` +qmk flash [-m <microcontroller>] <compiledFirmware.[bin|hex]> +``` + **Listing the Bootloaders** ``` @@ -352,6 +369,73 @@ $ qmk via2json -kb ai03/polaris -o polaris_keymap.json polaris_via_backup.json Ψ Wrote keymap to /home/you/qmk_firmware/polaris_keymap.json ``` +## `qmk import-keyboard` + +This command imports a data-driven `info.json` keyboard into the repo. + +**Usage**: + +``` +usage: qmk import-keyboard [-h] filename +``` + +**Example:** + +``` +$ qmk import-keyboard ~/Downloads/forever60.json +Ψ Importing forever60.json. + +Ψ Imported a new keyboard named forever60. +Ψ To start working on things, `cd` into keyboards/forever60, +Ψ or open the directory in your preferred text editor. +Ψ And build with qmk compile -kb forever60 -km default. +``` + +## `qmk import-keymap` + +This command imports a data-driven `keymap.json` keymap into the repo. + +**Usage**: + +``` +usage: qmk import-keymap [-h] filename +``` + +**Example:** + +``` +qmk import-keymap ~/Downloads/asdf2.json +Ψ Importing asdf2.json. + +Ψ Imported a new keymap named asdf2. +Ψ To start working on things, `cd` into keyboards/takashicompany/dogtag/keymaps/asdf2, +Ψ or open the directory in your preferred text editor. +Ψ And build with qmk compile -kb takashicompany/dogtag -km asdf2. +``` + +## `qmk import-kbfirmware` + +This command creates a new keyboard based on a [Keyboard Firmware Builder](https://kbfirmware.com/) export. + +**Usage**: + +``` +usage: qmk import-kbfirmware [-h] filename +``` + +**Example:** + +``` +$ qmk import-kbfirmware ~/Downloads/gh62.json +Ψ Importing gh62.json. + +⚠ Support here is basic - Consider using 'qmk new-keyboard' instead +Ψ Imported a new keyboard named gh62. +Ψ To start working on things, `cd` into keyboards/gh62, +Ψ or open the directory in your preferred text editor. +Ψ And build with qmk compile -kb gh62 -km default. +``` + --- # Developer Commands @@ -527,3 +611,4 @@ This command converts a TTF font to an intermediate format for editing, before c ## `qmk painter-convert-font-image` This command converts an intermediate font image to the QFF File Format. See the [Quantum Painter](quantum_painter.md?id=quantum-painter-cli) documentation for more information on this command. + diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index cee8986829..cc9c0b7f92 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -62,9 +62,17 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [MK20DX128](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-50-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-based-on-arm-cortex-m4-core:K20_50) * [MK20DX256](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72) * PJRC Teensy 3.2 + * [MK64FX512](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k6x-ethernet/kinetis-k64-120-mhz-256-kb-sram-microcontrollers-mcus-based-on-arm-cortex-m4-core:K64_120) + * PJRC Teensy 3.5 * [MK66FX1M0](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/k-series-cortex-m4/k6x-ethernet/kinetis-k66-180-mhz-dual-high-speed-full-speed-usbs-2mb-flash-microcontrollers-mcus-based-on-arm-cortex-m4-core:K66_180) * PJRC Teensy 3.6 +### Raspberry Pi + +* [RP2040](https://www.raspberrypi.com/documentation/microcontrollers/rp2040.html) + +For a detailed overview about the RP2040 support by QMK see the [dedicated RP2040 page](platformdev_rp2040.md). + ## Atmel ATSAM There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop). However, it is not recommended to design a board with this microcontroller as the support is quite specialized to Massdrop hardware. diff --git a/docs/config_options.md b/docs/config_options.md index 8227a0e074..3e011a5cc9 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -57,8 +57,6 @@ This is a C header file that is one of the first things included, and will persi * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define MATRIX_IO_DELAY 30` * the delay in microseconds when between changing matrix pin state and reading values -* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }` - * pins unused by the keyboard for reference * `#define MATRIX_HAS_GHOST` * define is matrix has ghost (unlikely) * `#define MATRIX_UNSELECT_DRIVE_HIGH` @@ -107,8 +105,10 @@ This is a C header file that is one of the first things included, and will persi * sets the maximum power (in mA) over USB for the device (default: 500) * `#define USB_POLLING_INTERVAL_MS 10` * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces -* `#define USB_SUSPEND_WAKEUP_DELAY 200` - * set the number of milliseconde to pause after sending a wakeup packet +* `#define USB_SUSPEND_WAKEUP_DELAY 0` + * sets the number of milliseconds to pause after sending a wakeup packet. + Disabled by default, you might want to set this to 200 (or higher) if the + keyboard does not wake up properly after suspending. * `#define F_SCL 100000L` * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`. @@ -141,7 +141,7 @@ If you define these options you will enable the associated feature, which may in ## Behaviors That Can Be Configured * `#define TAPPING_TERM 200` - * how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too + * how long before a key press becomes a hold * `#define TAPPING_TERM_PER_KEY` * enables handling for per key `TAPPING_TERM` settings * `#define RETRO_TAPPING` @@ -174,19 +174,12 @@ If you define these options you will enable the associated feature, which may in * sets the timer for leader key chords to run on each key press rather than overall * `#define LEADER_KEY_STRICT_KEY_PROCESSING` * Disables keycode filtering for Mod-Tap and Layer-Tap keycodes. Eg, if you enable this, you would need to specify `MT(MOD_CTL, KC_A)` if you want to use `KC_A`. +* `#define MOUSE_EXTENDED_REPORT` + * Enables support for extended reports (-32767 to 32767, instead of -127 to 127), which may allow for smoother reporting, and prevent maxing out of the reports. Applies to both Pointing Device and Mousekeys. * `#define ONESHOT_TIMEOUT 300` * how long before oneshot times out * `#define ONESHOT_TAP_TOGGLE 2` * how many taps before oneshot toggle is triggered -* `#define QMK_KEYS_PER_SCAN 4` - * Allows sending more than one key per scan. By default, only one key event gets - sent via `process_record()` per scan. This has little impact on most typing, but - if you're doing a lot of chords, or your scan rate is slow to begin with, you can - have some delay in processing key events. Each press and release is a separate - event. For a keyboard with 1ms or so scan times, even a very fast typist isn't - going to produce the 500 keystrokes a second needed to actually get more than a - few ms of delay from this. But if you're doing chording on something with 3-4ms - scan times? You probably want this. * `#define COMBO_COUNT 2` * Set this to the number of combos that you're using in the [Combo](feature_combo.md) feature. Or leave it undefined and programmatically set the count. * `#define COMBO_TERM 200` @@ -194,7 +187,7 @@ If you define these options you will enable the associated feature, which may in * `#define COMBO_MUST_HOLD_MODS` * Flag for enabling extending timeout on Combos containing modifers * `#define COMBO_MOD_TERM 200` - * Allows for extending COMBO_TERM for mod keys while mid-combo. + * Allows for extending COMBO_TERM for mod keys while mid-combo. * `#define COMBO_MUST_HOLD_PER_COMBO` * Flag to enable per-combo COMBO_TERM extension and `get_combo_must_hold()` function * `#define COMBO_TERM_PER_COMBO` @@ -214,14 +207,12 @@ If you define these options you will enable the associated feature, which may in * `#define RGB_DI_PIN D7` * pin the DI on the WS2812 is hooked-up to -* `#define RGBLIGHT_ANIMATIONS` - * run RGB animations * `#define RGBLIGHT_LAYERS` * Lets you define [lighting layers](feature_rgblight.md?id=lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state. * `#define RGBLIGHT_MAX_LAYERS` * Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight.md?id=lighting-layers) are needed. * Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards. -* `#define RGBLIGHT_LAYER_BLINK` +* `#define RGBLIGHT_LAYER_BLINK` * Adds ability to [blink](feature_rgblight.md?id=lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action). * `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` * If defined, then [lighting layers](feature_rgblight?id=overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off. @@ -366,8 +357,8 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i * `SRC` * Used to add files to the compilation/linking list. * `LIB_SRC` - * Used to add files as a library to the compilation/linking list. - The files specified by `LIB_SRC` is linked after the files specified by `SRC`. + * Used to add files as a library to the compilation/linking list. + The files specified by `LIB_SRC` is linked after the files specified by `SRC`. For example, if you specify: ``` SRC += a.c @@ -420,7 +411,7 @@ Use these to enable or disable building certain features. The more you have enab * `NKRO_ENABLE` * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work * `RING_BUFFERED_6KRO_REPORT_ENABLE` - * USB 6-Key Rollover - Instead of stopping any new input once 6 keys are pressed, the oldest key is released and the new key is pressed. + * USB 6-Key Rollover - Instead of stopping any new input once 6 keys are pressed, the oldest key is released and the new key is pressed. * `AUDIO_ENABLE` * Enable the audio subsystem. * `KEY_OVERRIDE_ENABLE` diff --git a/docs/custom_matrix.md b/docs/custom_matrix.md index 8f6878f94a..6d6ae5e972 100644 --- a/docs/custom_matrix.md +++ b/docs/custom_matrix.md @@ -81,17 +81,17 @@ void matrix_init(void) { } uint8_t matrix_scan(void) { - bool matrix_has_changed = false; + bool changed = false; // TODO: add matrix scanning routine here // Unless hardware debouncing - use the configured debounce routine - debounce(raw_matrix, matrix, MATRIX_ROWS, changed); + changed = debounce(raw_matrix, matrix, MATRIX_ROWS, changed); // This *must* be called for correct keyboard behavior matrix_scan_quantum(); - return matrix_has_changed; + return changed; } ``` diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md index 6dcf10c04d..50d8bcb7b3 100644 --- a/docs/eeprom_driver.md +++ b/docs/eeprom_driver.md @@ -2,12 +2,15 @@ The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present. +Selecting the EEPROM driver is done in your keyboard's `rules.mk`: + Driver | Description -----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below. `EEPROM_DRIVER = i2c` | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below. `EEPROM_DRIVER = spi` | Supports writing to SPI-based 25xx EEPROM chips. See the driver section below. `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 @@ -43,8 +46,9 @@ Module | Equivalent `#define` | Source -----------------|---------------------------------|------------------------------------------ CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512` | <https://www.sparkfun.com/products/14764> RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C` | <https://www.sparkfun.com/products/14764> -24LC64 EEPROM | `#define EEPROM_I2C_24LC64` | <https://www.microchip.com/wwwproducts/en/24LC64> -24LC128 EEPROM | `#define EEPROM_I2C_24LC128` | <https://www.microchip.com/wwwproducts/en/24LC128> +24LC32A EEPROM | `#define EEPROM_I2C_24LC32A` | <https://www.microchip.com/en-us/product/24LC32A> +24LC64 EEPROM | `#define EEPROM_I2C_24LC64` | <https://www.microchip.com/en-us/product/24LC64> +24LC128 EEPROM | `#define EEPROM_I2C_24LC128` | <https://www.microchip.com/en-us/product/24LC128> 24LC256 EEPROM | `#define EEPROM_I2C_24LC256` | <https://www.sparkfun.com/products/525> MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895> @@ -54,13 +58,13 @@ MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/p 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: -`config.h` override | Description | Default Value ------------------------------------------------|--------------------------------------------------------------------------------------|-------------- -`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | SPI Slave select pin in order to inform that the EEPROM is currently being addressed | _none_ -`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR` | Clock divisor used to divide the peripheral clock to derive the SPI frequency | `64` -`#define EXTERNAL_EEPROM_BYTE_COUNT` | Total size of the EEPROM in bytes | 8192 -`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32 -`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2 +`config.h` override | Default Value | Description +-----------------------------------------------|---------------|------------------------------------------------------------------------------------- +`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | _none_ | SPI Slave select pin in order to inform that the EEPROM is currently being addressed +`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR` | `64` | Clock divisor used to divide the peripheral clock to derive the SPI frequency +`#define EXTERNAL_EEPROM_BYTE_COUNT` | `8192` | Total size of the EEPROM in bytes +`#define EXTERNAL_EEPROM_PAGE_SIZE` | `32` | Page size of the EEPROM in bytes, as specified in the datasheet +`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | `2` | The number of bytes to transmit for the memory location within the EEPROM !> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero. @@ -73,3 +77,84 @@ The only configurable item for the transient EEPROM driver is its size: `#define TRANSIENT_EEPROM_SIZE` | Total size of the EEPROM storage in bytes | 64 Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`. + +## Wear-leveling Driver Configuration :id=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 + +The wear-leveling driver has a few possible _backing stores_ that may be used by adding to your keyboard's `rules.mk` file: + +Driver | Description +----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +`WEAR_LEVELING_DRIVER = embedded_flash` | This driver is used for emulating EEPROM by writing to embedded flash on the MCU. +`WEAR_LEVELING_DRIVER = spi_flash` | This driver is used to address external SPI NOR Flash peripherals. +`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. + +## Wear-leveling Embedded Flash Driver Configuration :id=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. + +Configurable options in your keyboard's `config.h`: + +`config.h` override | Default | Description +-----------------------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_ | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration. +`#define WEAR_LEVELING_EFL_FLASH_SIZE` | _unset_ | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting. +`#define WEAR_LEVELING_LOGICAL_SIZE` | `1024` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. +`#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. + +## Wear-leveling SPI Flash Driver Configuration :id=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. + +Configurable options in your keyboard's `config.h`: + +`config.h` override | Default | Description +----------------------------------------------------|--------------------------------|-------------------------------------------------------------------------------------------------------------------------------- +`#define WEAR_LEVELING_EXTERNAL_FLASH_BLOCK_COUNT` | `1` | Number of blocks in the external flash used by the wear-leveling algorithm. +`#define WEAR_LEVELING_EXTERNAL_FLASH_BLOCK_OFFSET` | `0` | The index first block in the external flash used by the wear-leveling algorithm. +`#define WEAR_LEVELING_LOGICAL_SIZE` | `((block_count*block_size)/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. Result must be <= 64kB. +`#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. + +## Wear-leveling RP2040 Driver Configuration :id=wear_leveling-rp2040-driver-configuration + +This driver performs writes to the same underlying storage that the RP2040 executes its code. + +Configurable options in your keyboard's `config.h`: + +`config.h` override | Default | Description +------------------------------------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------- +`#define WEAR_LEVELING_RP2040_FLASH_SIZE` | `PICO_FLASH_SIZE_BYTES` | Number of bytes of flash on the board. +`#define WEAR_LEVELING_RP2040_FLASH_BASE` | `(flash_size-sector_size)` | The byte-wise location that the backing storage should be located. +`#define WEAR_LEVELING_LOGICAL_SIZE` | `4096` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. +`#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 + +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. + +By default, `1024` bytes of emulated EEPROM is provided: + +MCU | EEPROM Provided | Flash Used +----------|-----------------|-------------- +STM32F042 | `1024` bytes | `2048` bytes +STM32F070 | `1024` bytes | `2048` bytes +STM32F072 | `1024` bytes | `2048` bytes +STM32F401 | `1024` bytes | `16384` bytes +STM32F411 | `1024` bytes | `16384` bytes + +Under normal circumstances configuration of this driver requires intimate knowledge of the MCU's flash structure -- reconfiguration is at your own risk and will require referring to the code. diff --git a/docs/faq_debug.md b/docs/faq_debug.md index fba27c5f68..4a35997222 100644 --- a/docs/faq_debug.md +++ b/ |