djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

improve dualbank and storage extension docs

Browse Source
This commit is contained in:
MicroDev 2023-01-29 16:12:05 +05:30
parent a226c9c83c
commit 4ef363a797
No known key found for this signature in database
GPG Key ID: 2C0867BE60967730
2 changed files with 31 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
shared-bindings/dualbank/__init__.c
View File

@ -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 small chunks.
//| This can be called multiple times when flashing the firmware in smaller 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.
//| """
//| ...
//|

5
shared-bindings/storage/__init__.c
View File

@ -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."""
//| ...
//|