Merge pull request #7503 from MicroDev1/dualbank

microdev1 · web-flow · commit 2f71f612d82c · 2023-01-30T02:18:53.000+05:30
Improve dualbank and storage extension docs
diff --git a/shared-bindings/dualbank/__init__.c b/shared-bindings/dualbank/__init__.c
@@ -30,25 +30,32 @@
 #include "supervisor/flash.h"
 #endif
 
-//| """DUALBANK Module
+//| """Dualbank Module
 //|
-//| The `dualbank` module adds ability to update and switch
-//| between the two app partitions.
+//| The `dualbank` module adds ability to update and switch between the
+//| two identical app partitions, which can contain different firmware versions.
 //|
-//| There are two identical partitions, these contain different
-//| firmware versions.
 //| Having two partitions enables rollback functionality.
 //|
-//| The two partitions are defined as boot partition and
-//| next-update partition. Calling `dualbank.flash()` writes
-//| the next-update partition.
+//| The two partitions are defined as the boot partition and the next-update partition.
+//| Calling `dualbank.flash()` writes the next-update partition.
 //|
-//| After the next-update partition is written a validation
-//| check is performed and on a successful validation this
-//| partition is set as the boot partition. On next reset,
-//| firmware will be loaded from this partition.
+//| After the next-update partition is written a validation check is performed
+//| and on a successful validation this partition is set as the boot partition.
+//| On next reset, firmware will be loaded from this partition.
 //|
-//| Here is the sequence of commands to follow:
+//| Use cases:
+//|     * Can be used for ``OTA`` Over-The-Air updates.
+//|     * Can be used for ``dual-boot`` of different firmware versions or platforms.
+//|
+//| .. note::
+//|
+//|     Boards with flash ``=2MB``:
+//|         This module is unavailable as the flash is only large enough for one app partition.
+//|
+//|     Boards with flash ``>2MB``:
+//|         This module is enabled/disabled at runtime based on whether the ``CIRCUITPY`` drive
+//|         is extended or not. See `storage.erase_filesystem()` for more information.
 //|
 //| .. code-block:: python
 //|
@@ -68,10 +75,12 @@ STATIC void raise_error_if_storage_extended(void) {
 #endif
 
 //| def flash(buffer: ReadableBuffer, offset: int = 0) -> None:
-//|     """Writes one of two app partitions at the given offset.
+//|     """Writes one of the two app partitions at the given offset.
+//|
+//|     This can be called multiple times when flashing the firmware in smaller chunks.
 //|
-//|     This can be called multiple times when flashing the firmware
-//|     in small chunks.
+//|     :param ReadableBuffer buffer: The entire firmware or a partial chunk.
+//|     :param int offset: Start writing at this offset in the app partition.
 //|     """
 //|     ...
 //|
@@ -102,10 +111,9 @@ STATIC mp_obj_t dualbank_flash(size_t n_args, const mp_obj_t *pos_args, mp_map_t
 STATIC MP_DEFINE_CONST_FUN_OBJ_KW(dualbank_flash_obj, 0, dualbank_flash);
 
 //| def switch() -> None:
-//|     """Switches the boot partition.
+//|     """Switches to the next-update partition.
 //|
-//|     On next reset, firmware will be loaded from the partition
-//|     just switched over to.
+//|     On next reset, firmware will be loaded from the partition just switched over to.
 //|     """
 //|     ...
 //|
diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c
@@ -166,8 +166,11 @@ MP_DEFINE_CONST_FUN_OBJ_1(storage_getmount_obj, storage_getmount);
 //|         extended by setting this to `True`. If this isn't provided or
 //|         set to `None` (default), the existing configuration will be used.
 //|
+//|     .. note:: New firmware starts with storage extended. In case of an existing
+//|          filesystem (e.g. uf2 load), the existing extension setting is preserved.
+//|
 //|     .. warning:: All the data on ``CIRCUITPY`` will be lost, and
-//|          CircuitPython will restart on certain boards."""
+//|         CircuitPython will restart on certain boards."""
 //|     ...
 //|
 
