docs: more docs in embassy-boot crate documentation

2 files changed, 22 insertions, 1 deletions

diff --git a/docs/modules/ROOT/pages/bootloader.adoc b/docs/modules/ROOT/pages/bootloader.adoc
index b7215e52a..3b0cdb182 100644
--- a/docs/modules/ROOT/pages/bootloader.adoc
+++ b/docs/modules/ROOT/pages/bootloader.adoc
@@ -45,6 +45,8 @@ The BOOTLOADER_STATE partition must be big enough to store one word per page in
 
 The bootloader has a platform-agnostic part, which implements the power fail safe swapping algorithm given the boundaries set by the partitions. The platform-specific part is a minimal shim that provides additional functionality such as watchdogs or supporting the nRF52 softdevice.
 
+NOTE: The linker scripts for the application and bootloader look similar, but the FLASH region must point to the BOOTLOADER partition for the bootloader, and the ACTIVE partition for the application.
+
 === FirmwareUpdater
 
 The `FirmwareUpdater` is an object for conveniently flashing firmware to the DFU partition and subsequently marking it as being ready for swapping with the active partition on the next reset. Its principle methods are `write_firmware`, which is called once per the size of the flash "write block" (typically 4KiB), and `mark_updated`, which is the final call.
@@ -91,4 +93,4 @@ cp $FIRMWARE_DIR/myfirmware $FIRMWARE_DIR/myfirmware+signed
 tail -n1 $SECRETS_DIR/message.txt.sig | base64 -d -i - | dd ibs=10 skip=1 >> $FIRMWARE_DIR/myfirmware+signed
 ----
 
-Remember, guard the `$SECRETS_DIR/key.sec` key as compromising it means that another party can sign your firmware.
\ No newline at end of file
+Remember, guard the `$SECRETS_DIR/key.sec` key as compromising it means that another party can sign your firmware.
diff --git a/embassy-boot/boot/README.md b/embassy-boot/boot/README.md
index 07755bc6c..3fc81f24b 100644
--- a/embassy-boot/boot/README.md
+++ b/embassy-boot/boot/README.md
@@ -8,6 +8,24 @@ The bootloader can be used either as a library or be flashed directly with the d
 
 By design, the bootloader does not provide any network capabilities. Networking capabilities for fetching new firmware can be provided by the user application, using the bootloader as a library for updating the firmware, or by using the bootloader as a library and adding this capability yourself.
 
+## Overview
+
+The bootloader divides the storage into 4 main partitions, configurable when creating the bootloader instance or via linker scripts:
+
+* BOOTLOADER - Where the bootloader is placed. The bootloader itself consumes about 8kB of flash, but if you need to debug it and have space available, increasing this to 24kB will allow you to run the bootloader with probe-rs.
+* ACTIVE - Where the main application is placed. The bootloader will attempt to load the application at the start of this partition. The minimum size required for this partition is the size of your application.
+* DFU - Where the application-to-be-swapped is placed. This partition is written to by the application. This partition must be at least 1 page bigger than the ACTIVE partition.
+* BOOTLOADER STATE - Where the bootloader stores the current state describing if the active and dfu partitions need to be swapped. 
+
+For any partition, the following preconditions are required:
+
+* Partitions must be aligned on the page size.
+* Partitions must be a multiple of the page size.
+
+The linker scripts for the application and bootloader look similar, but the FLASH region must point to the BOOTLOADER partition for the bootloader, and the ACTIVE partition for the application.
+
+For more details on the bootloader, see [the documentation](https://embassy.dev/book/dev/bootloader.html).
+
 ## Hardware support
 
 The bootloader supports different hardware in separate crates:
@@ -16,6 +34,7 @@ The bootloader supports different hardware in separate crates:
 * `embassy-boot-rp` - for the RP2040 microcontrollers.
 * `embassy-boot-stm32` - for the STM32 microcontrollers.
 
+
 ## Minimum supported Rust version (MSRV)
 
 `embassy-boot` is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.