README in Filesystem example is inconsistent with actual code

[crasbe]

Description

Hello everyone,

we are currently developing an application for the nRF52 microcontroller which is supposed to have a LittleFS filesystem on an external NOR flash. We had an old version of RIOT which had the old filesystem example with LittleFS, but when I checked the newer version, the code in the example had no mention of LittleFS anymore. The change was made on Aug 21, 2022 by this commit: https://github.com/RIOT-OS/RIOT/commit/e657590ce09dd1ad9bc80b57e9945446d4766fef

From what I understand, the VFS subsystem is based on LittleFS now, which is why the dedicated code was removed. However when building and executing the example for the "nrf52dk" target, it appears that only the "ConstFS" filesystem exists and nothing in regard to LittleFS. The example commands "vfs format /nvm0" and "vfs mount /nvm0" only result in an error, probably because the example code does not initialize it.

This is the console log with my nRF52-DK:

$ tio --map INLCRNL /dev/ttyACM0
[tio 14:49:29] tio v1.32
[tio 14:49:29] Press ctrl-t q to quit
[tio 14:49:29] Connected
 
> vfs df
Mountpoint              Total         Used    Available     Use%
/const                   27 B         27 B          0 B     100%
> 
> vfs format /nvm0
vfs: unsupported sub-command "format"
> 
> vfs mount /nvm0
vfs: unsupported sub-command "mount"
> 
> vfs ls /const
hello-world	14 B
hello-riot	13 B
total 2 files
> 
[tio 14:50:13] Disconnected

Essentially, the example is completely missing the following features described in the README:

• how to mount/format/unmount a file system, either with spiffs, littlefs, fatfs or constfs
• how to open/read/write/close a file with and without newlib In RIOT, most file systems use a mtd as flash interface. So to use this example one must define MTD_0. MTD_0 is a pointer to a mtd_dev_t instance. This example uses littlefs as default file system on the whole mtd. A constfs file system is also demonstrated with two files.

And the following shell commands are missing:

vfs format /nvm0: should be called the first time only, it will format the /nvm0 mountpoint with the configured file system vfs mount /nvm0: mount the file system on the configured mount point The constfs file system is mounted automatically on /const when the application starts vfs umount /nvm0: unmount /nvm0

I'm just getting started with RIOT, so I can't really say what's the direction this should go. Of couse, the README should reflect the actual functionality, but I feel like the functionality of the example was significantly cut with the aforementioned commit. Especially since now there is no example (or I didn't find it?) that shows how to use an SD card or other mass storage devices with LittleFS in RIOT.

Thanks and best regards, Chris

Useful Links

Link to the current Filesystem Example: https://github.com/RIOT-OS/RIOT/tree/master/examples/filesystem Link to the previous Filesystem Example: https://github.com/RIOT-OS/RIOT/tree/777e148bc286cf055e5ec299d55e6b229660f121/examples/filesystem Link to the Commit Details: https://github.com/RIOT-OS/RIOT/commit/e657590ce09dd1ad9bc80b57e9945446d4766fef

[benpicco]

Oh sorry for forgetting to update the Readme. The idea is that boards now will define what filesystems they have on their MTD devies and that they will be mounted automatically, so the application does not have to deal with this at all.

If you are using a board with a pre-defined filesystem, try adding

USEMODULE += vfs_auto_format

to your Makefile - this should automatically create the filesystem if it can not be mounted.

If you have a custom board, you need to add a mountpoint next to your MTD definition, e.g. nrf52840dk has

VFS_AUTO_MOUNT(littlefs2, VFS_MTD(nrf52840dk_nor_dev), VFS_DEFAULT_NVM(0), 0);

The 'default' filesystem is selected via the virtual vfs_default module with which the board selects the actual filesystem:

# default to using littlefs2 on the external flash
ifneq (,$(filter vfs_default,$(USEMODULE)))
  USEPKG += littlefs2
  USEMODULE += mtd
endif

[crasbe]

That's a good hint to the nrf52840dk, as it has a Flash memory onboard, which the nRF52DK with the nRF52832 microcontroller does not.

In fact we have ordered some nRF52840 DKs which should arrive this week, so perhaps this could serve as an example in the updated README.

[maribu]

Is there still a doc update pending, or has everything been resolved?

[crasbe]

@maribu I created a pull request with an updated README.

Furthermore I found when testing the filesystem example on the real board, that the stack size is insufficient and therefore added an option in the Makefile to increase it and added a remark about that in the README.

The output was something like this here:

> vfs mkdir /nvm0/test
mkdir: mkdir: /nvm0/test
*** RIOT kernel panic:
MEM MANAGE HANDLER

	pid | name                 | state    Q | pri | stack  ( used) ( free) | base addr  | current     
	  - | isr_stack            | -        - |   - |    512 (  448) (   64) | 0x20000000 | 0x20000160
	  1 | main                 | bl mutex _ |   7 |   1536 ( 1496) (   40) | 0x20000400 | 0x20000984 
	    | SUM                  |            |     |   2048 ( 1944) (  104)

*** halted.

Inside isr -12

Context before hardfault:
main(): This is RIOT! (Version: 2024.04-devel-254-gee0f6d)
constfs mounted successfully

I hope that the combination of these two issues is not against the guidelines, this is my first contribution to RIOT.