docs: add more faqs, update storage doc

Signed-off-by: Haobo Gu <[email protected]>

docs/src/faq.md

@@ -33,3 +33,52 @@ run `cargo clean` and then `cargo run --release`. Open an [issue](https://github
 ## rust-lld: error: section will not fit in region 'FLASH': overflowed by x bytes
 
 This is because your MCU's flash is too small. Try building in release mode: `cargo build --release`. For check out our [`binary size optimization`](https://haobogu.github.io/rmk/binary_size.html) doc
+
+## ERROR: Storage is full
+
+By default, RMK uses only 2 sectors of your microcontroller's internal flash. You may get the following error if 2 sectors is not big enough to store all your keymaps: 
+
+```
+ERROR Storage is full
+└─ rmk::storage::print_sequential_storage_err @ /Users/haobogu/Projects/keyboard/rmk/rmk/src/storage.rs:577 
+ERROR Got none when reading keymap from storage at (layer,col,row)=(1,5,8)
+└─ rmk::storage::{impl#2}::read_keymap::{async_fn#0} @ /Users/haobogu/Projects/keyboard/rmk/rmk/src/storage.rs:460 
+ERROR Keymap reading aborted!
+└─ rmk::keymap::{impl#0}::new_from_storage::{async_fn#0} @ /Users/haobogu/Projects/keyboard/rmk/rmk/src/keymap.rs:38  
+```
+
+If you have more sectors available in your internal flash, you can increase `num_sectors` in `[storage]` section of your `keyboard.toml`, or change `storage_config` in your [`RmkConfig`](https://docs.rs/rmk-config/0.1.0/rmk_config/keyboard_config/struct.RmkConfig.html) if you're using Rust API.
+
+## panicked at 'embassy-executor: task arena is full.
+
+The current embassy requires manually setting of the task arena size. By default, RMK set's it to 8192 in all examples:
+
+```toml
+# Cargo.toml
+embassy-executor = { version = "0.5", features = [
+    "defmt",
+    "arch-cortex-m",
+    "task-arena-size-8192",
+    "executor-thread",
+    "integrated-timers",
+] }
+```
+
+If you got `ERROR panicked at 'embassy-executor: task arena is full.` error after flashing to your MCU, that means that you should increase your embassy's task arena. Embassy has a series cargo features to do this, for example, changing task arena size to 65536:
+
+```diff
+# Cargo.toml
+embassy-executor = { version = "0.5", features = [
+    "defmt",
+    "arch-cortex-m",
+-   "task-arena-size-8192",
++   "task-arena-size-65536",
+    "executor-thread",
+    "integrated-timers",
+] }
+```
+
+In the latest git version of embassy, task arena size could be calculated automatically, but it requires **nightly** version of Rust.
+
+If you're comfortable with nightly Rust, you can enable `nightly` feature of embassy-executor and remove `task-arena-size-*` feature.
+

docs/src/storage.md

@@ -1,13 +1,38 @@
 # Storage
 
-TODO: Update storage documentation
+Storage feature is used by saving keymap edits to internal flash. 
 
-Storage feature is used by saving keymap edits to internal flash. By default, it uses **last 2 sectors** of your microcontroller's internal flash. So you have to ensure that you have enough flash space for storage feature if you pass the storage argument to RMK. If there is not enough space, passing `None` is acceptable.
+## Storage configuration
 
-If you're using nrf528xx + BLE, this feature is automatically enabled because it's required to saving BLE bond info. 
+If you're using the `keyboard.toml`, you can set the storage using the following config:
 
-Future work: 
+```toml
+[storage]
+# Storage feature is enabled by default
+enabled = true
+# Start address of local storage, MUST BE start of a sector.
+# If start_addr is set to 0(this is the default value), the last `num_sectors` sectors will be used.
+start_addr = 0x00000000
+# How many sectors are used for storage, the default value is 2
+num_sectors = 2
+```
 
-- [ ] make it configurable that how many sectors to be used(but at least 2)
-- [ ] add storage to RMK feature gate, disable all related stuffs if the feature is not enabled. This could save a lot of flash
-- [ ] Save more configurations to storage
+You can also edit `storage_config` field in `RmkConfig` if you're using Rust API:
+
+```rust
+// https://github.com/HaoboGu/rmk/blob/main/examples/use_rust/nrf52832_ble/src/main.rs#L48
+
+let storage_config = StorageConfig {
+    start_addr: 0x70000,
+    num_sectors: 2,
+};
+let keyboard_config = RmkConfig {
+    usb_config: keyboard_usb_config,
+    vial_config,
+    storage_config,
+    ..Default::default()
+};
+
+```
+
+By default, RMK uses **last 2 sectors** of your microcontroller's internal flash as the storage space. So you have to ensure that you have enough flash space for storage feature. If there is not enough space, passing `None` is acceptable.