littlefs-project / littlefs-fuse

A FUSE wrapper that puts the littlefs in user-space

The little filesystem in user-space

A FUSE wrapper that puts the littlefs in user-space.

FUSE - https://github.com/libfuse/libfuse
littlefs - https://github.com/geky/littlefs

This project allows you to mount littlefs directly in a host PC. This allows you to easily debug an embedded system using littlefs on removable storage, or even debug littlefs itself, since the block device can be viewed in a hex-editor simultaneously.

littlefs-fuse uses FUSE to interact with the host OS kernel, which means it can be compiled into a simple user program without kernel modifications. This comes with a performance penalty, but works well for the littlefs, since littlefs is intended for embedded systems.

Currently littlefs-fuse has been tested on the following OSs:

• Linux
• FreeBSD

Usage on Linux

littlefs-fuse requires FUSE version 2.6 or higher, you can find your FUSE version with:

fusermount -V

In order to build against FUSE, you will need the package libfuse-dev:

sudo apt-get install libfuse-dev

Once you have cloned littlefs-fuse, you can compile the program with make:

make

This should have built the lfs program in the top-level directory.

From here we will need a block device. If you don't have removable storage handy, you can use a file-backed block device with Linux's loop devices:

sudo chmod a+rw /dev/loop0                  # make loop device user accessible
dd if=/dev/zero of=image bs=512 count=2048  # create a 1MB image
losetup /dev/loop0 image                    # attach the loop device

littlefs-fuse has two modes of operation, formatting and mounting.

To format a block device, pass the --format flag. Note! This will erase any data on the block device!

./lfs --format /dev/loop0

To mount, run littlefs-fuse with a block device and a mountpoint:

mkdir mount
./lfs /dev/loop0 mount

Once mounted, the littlefs filesystem will be accessible through the mountpoint. You can now use the littlefs like you would any other filesystem:

cd mount
echo "hello" > hi.txt
ls
cat hi.txt

After using littlefs, you can unmount and detach the loop device:

cd ..
umount mount
sudo losetup -d /dev/loop0

Usage on FreeBSD

littlefs-fuse requires FUSE version 2.6 or higher, you can find your FUSE version with:

pkg info fusefs-libs | grep Version

Once you have cloned littlefs-fuse, you can compile the program with make:

gmake

This should have built the lfs program in the top-level directory.

From here we will need a block device. If you don't have removable storage handy, you can use a file-backed block device with FreeBSD's loop devices:

dd if=/dev/zero of=imageBSD bs=1m count=1   # create a 1 MB image
sudo mdconfig -at vnode -f image            # attach the loop device
sudo chmod 666 /dev/mdX                     # make loop device user accessible,
                                            # where mdX is device created with mdconfig command

littlefs-fuse has two modes of operation, formatting and mounting.

To format a block device, pass the --format flag. Note! This will erase any data on the block device!

./lfs --format /dev/md0

To mount, run littlefs-fuse with a block device and a mountpoint:

mkdir mount
./lfs /dev/md0 mount

Once mounted, the littlefs filesystem will be accessible through the mountpoint. You can now use the littlefs like you would any other filesystem:

cd mount
echo "hello" > hi.txt
ls
cat hi.txt

After using littlefs, you can unmount and detach the loop device:

cd ..
umount mount
sudo mdconfig -du 0

Limitations

As an embedded filesystem, littlefs is designed to be simple. By default, this comes with a number of limitations compared to more PC oriented filesystems:

• No timestamps, this will cause some programs, such as make to fail
• No user permissions, this is why all of the files show up bright green in ls, all files are accessible by anyone
• No symbolic links or special device files, currently only regular and directory file-types are implemented

Tips

If the littlefs was formatted with different geometry than the physical block device, you can override what littlefs-fuse detects. lfs -h lists all available options:

./lfs --block_size=512 --format /dev/loop0
./lfs --block_size=512 /dev/loop0 mount

You can run littlefs-fuse in debug mode to get a log of the kernel interactions with littlefs-fuse. Any printfs in the littlefs driver will end up here:

./lfs -d /dev/loop0 mount

You can even run littlefs-fuse in gdb to debug the filesystem under user operations. Note! When gdb is halted this will freeze any programs interacting with the filesystem!

make DEBUG=1 clean all                # build with debug info
gdb --args ./lfs -d /dev/loop0 mount  # run with gdb

Using xxd or other hex-editory is very useful for inspecting the block device while debugging. You can even run xxd from inside gdb using gdb's ! syntax:

dd if=/dev/loop0 bs=512 count=1 skip=0 | xxd -g1

littlefs-fuse's Issues

file size directly after write wrong

Following code write 1MB to the file "test" and immediately checks for the file size via fstat. The result should be 1MB, but is actually 0. However, when I start the program a second time with a existing file the result is correct.

#include<stdio.h>
#include<stdlib.h>
#include<sys/types.h>
#include<sys/stat.h>
#include<fcntl.h>
#include<unistd.h>
#include<fcntl.h>

size_t fsize(int fd)
{
    struct stat st;
    if (fstat(fd, &st) != 0)
    {
        perror("stat");
        exit(1);
    }
    return st.st_size;
}

int main()
{
    char data[1024*1024];
    int fd = open("test", O_RDWR | O_CREAT | O_TRUNC, S_IRWXU);
    if (fd == -1)
    {
            perror("Error during open");
            exit(1);
    }
    write(fd, data, sizeof data);
    printf("%zu\n", fsize(fd));
    close(fd);

    return 0;
}

Ubuntu package

I don't know about you but I always prefer a properly versioned binary package to building something ad-hoc from sources.
I'm filing it as an issue rather than as a pull request, but if you'd like to adopt it, it's essentially done.
This branch adds the necessary scaffolding for building a Debian/Ubuntu package and i'm using it to publish packages to our PPA.

Once you have a Launchpad account and GPG key set up, it's just 3 commands to publish a release to a PPA:

 $ debian/build-ubuntu-release.sh
 $ debsign /tmp/work/*_source.changes
 $ dput ppa:mongoose-os/mos /tmp/work/*_source.changes

Ideally i'd like to see this merged and a PPA created with an official package but if you're not interested, feel free to close and I'll just keep it in our repo.

Build not working

Compiling the program with 'make' once littlefs-fuse has been cloned leads to this error:

lfs_fuse.c:15:23: fatal error: fuse/fuse.h: No such file or directory

My fusermount version is 2.9.4, which means that the fuse header file should be available, right?

littlefs fuse wrong lfsfuse_bd implementation

lfs_fuse_bd_prog / lfs_fuse_bd_read assumes that read / write syscall always read/write exactly the the number fo bytes as requested, so it is not true. When we use larger block size than 512 bytes it read/write returns less data than excepted and lfsfuse doesn't work properly.

Read zero bytes on newly truncated file

Following code creates a file and truncates it to 1MB. After that it tries to read the first 1MB. However, read command returns 0 bytes read, which is obviously wrong.

#include<stdio.h>
#include<stdlib.h>
#include<sys/types.h>
#include<sys/stat.h>
#include<fcntl.h>
#include<unistd.h>
#include<fcntl.h>

int main()
{
    char data[1024*1024];
    int fd = open("test", O_RDWR | O_CREAT | O_TRUNC, S_IRWXU);
    ftruncate(fd, sizeof data);
    lseek(fd, 0, SEEK_SET);
    int ret = read(fd, data, sizeof data);
    printf("bytes read: %i\n", ret);
    close(fd);
    return 0;
}

Add option to mount without upgrading disk version

While I can use the --disk-version option to specify mounting with a specific disk version, it would be really useful to have a switch such as --no-upgrade-disk-version which would automatically detect this version, and not upgrade the on-disk version.

compilation error: test.c interfering

hello,

the file "test.c" in the littlefs directory is interfering with compilation:

$ make
cc -Os -I. -Ilittlefs -std=c99 -Wall -pedantic -D_FILE_OFFSET_BITS=64 -D_XOPEN_SOURCE=700 lfs_fuse_bd.o lfs_fuse.o littlefs/lfs_util.o littlefs/test.o littlefs/lfs.o -lfuse -o lfs
littlefs/test.o: In function main': test.c:(.text.startup+0x0): multiple definition of main'
lfs_fuse.o:lfs_fuse.c:(.text.startup+0x0): first defined here
littlefs/test.o: In function main': test.c:(.text.startup+0x23): undefined reference to lfs_emubd_create'
test.c:(.text.startup+0x1ed): undefined reference to lfs_emubd_destroy' littlefs/test.o:(.rodata+0x8): undefined reference to lfs_emubd_read'
littlefs/test.o:(.rodata+0x10): undefined reference to lfs_emubd_prog' littlefs/test.o:(.rodata+0x18): undefined reference to lfs_emubd_erase'
littlefs/test.o:(.rodata+0x20): undefined reference to `lfs_emubd_sync'
collect2: error: ld returned 1 exit status
make: *** [Makefile:45: lfs] Error 1

The problem is that littlefs/test.c has a main(), as does lfs_fuse.c

Removing littlefs/test.c fixes the issue.

MbedOS lfs and littlefs-fuse - corrupted dir pair at 0 1

Hello,

I have tried to use littlefs-fuse to read data from a SD card that uses littlefs. My first approach was to use mbed-os-example-filesystem with SDBlockDevice as a BlockDevice for littlefs. The code works correctly on the micricontroller. However, I am not able to mount the SD card in Linux using littlefs-fuse. I am getting the following error:

./lfs /dev/sdb mount
lfs error:969: Corrupted dir pair at 0 1
lfs error:514: Invalid or incomplete multibyte or wide character

I have tried to reformat the SD card with littlefs-fuse and then use in in the microcontroller. Unfortunately I am getting the same error but this time it is littlefs from MbedOS that complains:

Mounting the filesystem... 
lfs error:493: Corrupted dir pair at 0 1
lfs error:2216: Invalid superblock at 0 1
Fail :(
No filesystem found, formatting... OK

I am using MbedOS 5.15.0 and littlefs-fuse build from this repository.

Truncate an existing file gives spurious error and unmounts filesystem

When I try the commands

mkdir -p mount
lfs --format /dev/loop0
lfs /dev/loop0 mount
cd mount
dd if=/dev/urandom of=temp bs=16 count=1
truncate -s 32 temp

on a existing loop block device I receive the error

truncate: failed to truncate 'temp' at 32 bytes: Numerical result out of range

Also the filesystem is unmounted afterwards.

[Question] Image created for uC

HI there,

---

Update (7/7/21):

For some reason, I can't read the file unless I create a second one. After that I can read the first file but not the second file and so on. The new file could be empty.

---

My question is similar to #23.
I created an image following the README steps on Ubuntu with a dummy TXT file, and I want to use the image on a uC (STM32L4 with Zephyr RTOS).
When I try to read the file, on the uC, it can list the file but can't read the content, it returns empty. I attached the image.zip

--- Available filters and text transformations: colorize, debug, default, direct, hexlify, log2file, nocontrol, printable, send_on_enter, time
--- More details at http://bit.ly/pio-monitor-filters
--- Miniterm on /dev/ttyACM0  115200,8,N,1 ---
--- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
*** Booting Zephyr OS build zephyr-v20500  ***
Area 4 at 0xfc000 on FLASH_CTRL for 16384 bytes
/lfs mount: 0
OK open /lfs/test.txt: 0
Read /lfs/test.txt file:  | Result: 0
/lfs/test.txt close: 0
/lfs opendir: 0
  F 0 test.txt
End of files
/lfs unmount: 0
[00:00:00.008,000] ␛[0m<inf> littlefs: LittleFS version 2.2, disk version 2.0␛[0m
[00:00:00.008,000] ␛[0m<inf> littlefs: FS at FLASH_CTRL:0xfc000 is 4 0x1000-byte blocks with 512 cycle␛[0m
[00:00:00.008,000] ␛[0m<inf> littlefs: sizes: rd 16 ; pr 16 ; ca 64 ; la 32␛[0m
[00:00:00.008,000] ␛[0m<inf> littlefs: /lfs mounted␛[0m
[00:00:00.022,000] ␛[0m<inf> littlefs: /lfs unmounted␛[0m

I have missed some configuration when I created the image?

Thank you

You might be interested in this

https://github.com/desertkun/littlefs-dokany

• Similar in the idea, but for Windows
• Has several issues but could be addressed

I could transfer ownership (and give it up legally) or you could just steal it.

LiitleFs made with Arduino-ESP-mklittlefs will not show any file

This Problem is (AFAIK) the same as described in Issue 28 & 31.
In my case, a FS made with mklittlefs from the Arduino-ESP8266 toolchain will show an empthy root-dir when mounted on the PC, but will work inside the esp.
If I made a fs as described in the readme, created files show up as expected.

Looking into both files (with a hex editor) it seams, that the first directory/file entry starts at a different position!

I will atach the file, that was created within the Arduino toolchain. It contains two files:

• /html/index.html
• /Config.json
  Both files can be accessed by the ESP.

(Just to clarify: Yes I do a "losetup /dev/loopX " and a "lfs /dev/loopX ")

One more remark:
The tool uses: pagesize=256 & blocksize=8192
Because I assumed that the problem lies in different asumptions about one of this parameters I try to use:
lfs -b 8192 /dev/loopX
This will issue:
No such file or directory
????

Feeder.ino.zip

2gb limit

I’ve formatted and mounted a 16gb sd card with the following commands:

./lfs --format /dev/sdb
./lfs /dev/sdb sd

Then I attempt to copy a big file to the sd card:

pv bigfile.zip > sd/bigfile.zip
Which results in:

1,97GiB 0:09:52 [5,44MiB/s] [==================================================================================>                                                                           ] 53% ETA 0:08:33
pv: write failed: Operation not permitted

Also writing multiple smaller files beyond 2^31 - 1 bytes fails. Is there a limit to the amount of data that can be written to the filesystem, using little-fs fuse?

Interestingly our microcontroller is able to write past this limit, but we can’t read the files beyond the 2gb limit with little-fs fuse.

edit: I'm on the master branch

Assertion on minimum block size < 128 bytes

There is an assertion that prevents the blocksize from being set lower than 128 bytes.

I have reasons, but I was trying to set a block size lower than that.

lfs: littlefs/lfs.c:4186: lfs_init: Assertion lfs->cfg->block_size >= 128' failed.`

Does LittleFS have that same limitation?

New releases?

Seems that the last tags are of 2.4.1 while littlefs was recently updated to 2.6.1

Would it be possible to tag all the releases, starting with the lates - 2.6.1?
It's good to have consistency but also include all versions so working and testing with specific littlefs version can be done.

Cannot see directory content in Midnight Commander

System verison: Kubuntu 22.04
Midnight commander version: 4.8.27
littlefs version: v2.5
littlefs disk version: v2.0
FUSE library version: 2.9.9
fusermount3 version: 3.10.5
using FUSE kernel interface version 7.19

Description:
I mount filesystem ($l is loop device]:
lfs --block_size=4096 --block_count=32 --block_cycles=500 --read_size=1 --prog_size=256 --cache_size=256 --lookahead_size=16 $l mount

If I use ls -l, I can see files/directories in mounted directory. If I use midnight commander, mount directory seems to be empty.
I debugged your code and found out that lfs_fuse_readdir is called twice when content of directory in midnight commander is loaded. Second call to this function does not find any file/directory.

I worked around this by calling:
lfs_dir_rewind(&lfs, dir);
before while loop.

Mount by custom channel

First of all, thank you very much for this project.

I have a microcontroller with external flash chip with littlefs on it, and I need a way to transfer files to the device from pc.

The problem is, i don't use SD cards, but I have a way to communicate with device using uart.

Is there a way I can implement managing blocks myself so littlefs-fuse can mount my implementation?

Something like I open a unix domain socket on my external program and then I mount littlefs-fuse directly into it.

Compilation error on recent Fedora system

I tried to compile according to the instructions, but no luck:

$ make
cc -c -MMD -Os -I. -Ilittlefs -std=c99 -Wall -pedantic -D_FILE_OFFSET_BITS=64 -D_XOPEN_SOURCE=700 lfs_fuse_bd.c -o lfs_fuse_bd.o
lfs_fuse_bd.c:15:10: fatal error: stropts.h: No such file or directory
#include <stropts.h>
^~~~~~~~~~~
compilation terminated.
make: *** [Makefile:51: lfs_fuse_bd.o] Error 1

Apparently stropts.h has not been distributed in Fedora for about a decade, so probably it should be removed.

Usage question

Hello,

Can littlefs-fuse be used to mount an existing file system image? For example, I'm able to get the binary from the flash chip we're using with LFS... I mount this file using the method shown in the README, but no data is shown. I can create new files and they are written to the binary file, but the existing data isn't shown by ls. When I use LFS on the target, the directories are seen and the files are able to be written to. I've verified that the data does seem to be in the binary as well. The names of the directories that I've made are in there, at least.

Thank you!

lfs_fuse_bd_erase should be implemented

Expected behavior:
I have an rpi-pico program where littlefs is used. I want to prepare the filesystem in my PC and then flash this filesystem into the rpi-pico. After filesystem is flashed into rpi-pico, rpi-pico has read/write access to this prepared filesystem.
Rpi-pico should be able to write to the prepared filesystem

Actual behavior:
Rpi-pico cannot write to the filesystem. When it does, filesystem is corrupted.

Information about the issue:
Rpi-pico needs to erase blocks (fill it with 0xFF values) before write. littlefs-fuse does not do that. When I put breakpoint into
my "prog" function in rpi-pico and examine data in the flash at that place, it still contains some data and it is not erased.
It would be nice to implement erase function and fill blocks with value 0xFF. It can be optional by commandline argument.
Maybe some flashes need to fill blocks with 0x00 too.