From 7090fc5dd63bc1dcbe5470e2000ed333cb867d64 Mon Sep 17 00:00:00 2001 From: Ned Konz Date: Wed, 1 Oct 2025 10:56:41 -0700 Subject: zephyr: Mount all disks and flash partition, formatting if necessary. Existing C code in `main.c` only mounts a flash filesystem if one exists, and doesn't do anything if the 'storage' partition is not formatted. This commit moves the mounting logic from `main.c` to frozen code using `modules/_boot.py` and adds the formatting of a previously unformatted partition if the mount fails. Every available disk (in the newly added `DiskAccess.disks` tuple) will be mounted on separate mount points (if they're formatted), and the 'storage' flash partition (if any) will be mounted on /flash (and will be formatted as LFS2 if necessary). Also, `sys.path` will be updated with appropriate 'lib' subdirectories for each mounted filesystem. The current working directory will be changed to the last `DiskAccess.disk` mounted, or to /flash if no disks were mounted. Then `boot.py` and `main.py` will be executed from the current working directory if they exist. Thanks to @VynDragon for the logic in `zephyr/zephyr_storage.c`. Signed-off-by: Ned Konz --- docs/zephyr/quickref.rst | 14 ++++++---- docs/zephyr/tutorial/storage.rst | 56 ++++++++++++++++++++++++++++++++++------ 2 files changed, 57 insertions(+), 13 deletions(-) (limited to 'docs/zephyr') diff --git a/docs/zephyr/quickref.rst b/docs/zephyr/quickref.rst index 6025092a0..78d465050 100644 --- a/docs/zephyr/quickref.rst +++ b/docs/zephyr/quickref.rst @@ -135,11 +135,14 @@ the ``io-channels`` property containing all the ADC channels):: Disk Access ----------- -Use the :ref:`zephyr.DiskAccess ` class to support filesystem:: +Storage devices such as SD cards are automatically mounted at startup (e.g., at ``/sd``). +For manual mounting, use the :ref:`zephyr.DiskAccess ` class:: import vfs from zephyr import DiskAccess + print(DiskAccess.disks) # list available disk names, e.g., ('SDHC',) + block_dev = DiskAccess('SDHC') # create a block device object for an SD card vfs.VfsFat.mkfs(block_dev) # create FAT filesystem object using the disk storage block vfs.mount(block_dev, '/sd') # mount the filesystem at the SD card subdirectory @@ -152,12 +155,15 @@ Use the :ref:`zephyr.DiskAccess ` class to support filesystem Flash Area ---------- -Use the :ref:`zephyr.FlashArea ` class to support filesystem:: +Flash storage is automatically mounted at ``/flash`` at startup with automatic filesystem creation. +For manual mounting, use the :ref:`zephyr.FlashArea ` class:: import vfs from zephyr import FlashArea - block_dev = FlashArea(4, 4096) # creates a block device object in the frdm-k64f flash scratch partition + print(FlashArea.areas) # list available areas, e.g., {'storage': 1, 'scratch': 4} + + block_dev = FlashArea(FlashArea.areas['scratch'], 4096) # creates a block device object using the scratch partition vfs.VfsLfs2.mkfs(block_dev) # create filesystem in lfs2 format using the flash block device vfs.mount(block_dev, '/flash') # mount the filesystem at the flash subdirectory @@ -166,8 +172,6 @@ Use the :ref:`zephyr.FlashArea ` class to support filesystem:: f.write('Hello world') # write to the file print(open('/flash/hello.txt').read()) # print contents of the file -The ``FlashAreas``' IDs that are available are listed in the FlashArea module, as ``ID_*``. - Sensor ------ diff --git a/docs/zephyr/tutorial/storage.rst b/docs/zephyr/tutorial/storage.rst index 7fd449226..835d239b6 100644 --- a/docs/zephyr/tutorial/storage.rst +++ b/docs/zephyr/tutorial/storage.rst @@ -8,6 +8,27 @@ Zephyr DiskAccess or FlashArea (flash map) APIs depending on which the board sup See `vfs Filesystem Mounting `_. +Automatic Filesystem Mounting +------------------------------ + +MicroPython on Zephyr automatically attempts to mount available storage at startup: + +1. **Flash storage** (if available): Automatically mounted at ``/flash`` using the + littlefs2 filesystem. If the filesystem doesn't exist, it will be created + automatically. + +2. **Disk storage** (such as SD cards): Automatically detected and mounted at + ``/`` (e.g., ``/sd`` for SD cards). + +3. **Working directory**: The working directory is set to the mounted disk if + available, otherwise to ``/flash`` if flash storage is available. + +4. **Module search path**: The ``sys.path`` is automatically updated to include + ``//lib`` for each mounted disk and ``/flash/lib`` for flash storage. + +This automatic mounting is performed by the ``_boot.py`` module at startup. For most +use cases, you don't need to manually mount filesystems. + Disk Access ----------- @@ -19,17 +40,26 @@ For use with SD card controllers, SD cards must be present at boot & not removed be auto detected and initialized by filesystem at boot. Use the disk driver interface and a file system to access SD cards via disk access (see below). +The available disk names can be accessed via the ``DiskAccess.disks`` attribute, which contains +a tuple of available disk names (e.g., ``('SDHC',)`` or ``('SD',)``). + Example usage of FatFS with an SD card on the mimxrt1050_evk board:: import vfs from zephyr import DiskAccess - bdev = zephyr.DiskAccess('SDHC') # create block device object using DiskAccess + + # List available disks + print(DiskAccess.disks) # prints available disk names, e.g., ('SDHC',) + + bdev = DiskAccess('SDHC') # create block device object using DiskAccess vfs.VfsFat.mkfs(bdev) # create FAT filesystem object using the disk storage block vfs.mount(bdev, '/sd') # mount the filesystem at the SD card subdirectory with open('/sd/hello.txt','w') as f: # open a new file in the directory f.write('Hello world') # write to the file print(open('/sd/hello.txt').read()) # print contents of the file +Note: In most cases, disks are automatically mounted at startup and manual mounting is not necessary. + Flash Area ---------- @@ -41,16 +71,26 @@ API is recommended (see below). This class uses `Zephyr Flash map API `_ and implements the `vfs.AbstractBlockDev` protocol. +The available flash area names can be accessed via the ``FlashArea.areas`` dictionary, which maps partition +labels to their IDs (e.g., ``{'storage': 1, 'scratch': 4}``). + Example usage with the internal flash on the reel_board or the rv32m1_vega_ri5cy board:: import vfs from zephyr import FlashArea - bdev = FlashArea(FlashArea.STORAGE, 4096) # create block device object using FlashArea - vfs.VfsLfs2.mkfs(bdev) # create Little filesystem object using the flash area block - vfs.mount(bdev, '/flash') # mount the filesystem at the flash storage subdirectory - with open('/flash/hello.txt','w') as f: # open a new file in the directory - f.write('Hello world') # write to the file - print(open('/flash/hello.txt').read()) # print contents of the file + + # List available flash areas + print(FlashArea.areas) # prints available areas, e.g., {'storage': 1, 'scratch': 4} + + bdev = FlashArea(FlashArea.areas['storage'], 4096) # create block device object using FlashArea + vfs.VfsLfs2.mkfs(bdev) # create Little filesystem object using the flash area block + vfs.mount(bdev, '/flash') # mount the filesystem at the flash storage subdirectory + with open('/flash/hello.txt','w') as f: # open a new file in the directory + f.write('Hello world') # write to the file + print(open('/flash/hello.txt').read()) # print contents of the file + +Note: In most cases, the flash storage partition is automatically mounted at ``/flash`` at startup with +automatic filesystem creation if needed, so manual mounting is not necessary. For boards such as the frdm_k64f in which the MicroPython application spills into the default flash storage -partition, use the scratch partition by replacing ``FlashArea.STORAGE`` with the integer value 4. +partition, use the scratch partition by replacing ``'storage'`` with ``'scratch'``. -- cgit v1.2.3