Skip to content

Improve dualbank and storage extension docs #7503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 29, 2023
Merged

Improve dualbank and storage extension docs #7503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 27 additions & 19 deletions shared-bindings/dualbank/__init__.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
//|
Expand All @@ -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.
//| """
//| ...
//|
Expand Down Expand Up @@ -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.
//| """
//| ...
//|
Expand Down
5 changes: 4 additions & 1 deletion shared-bindings/storage/__init__.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
//| ...
//|

Expand Down