Add VFS to enable POSIX file I/O operations (#2333)

* Add VFS to enable POSIX file I/O operations

Enables use of FILE * operations on internal and external storage.  fopen,
fclose, fseek, fprintf, fscanf, etc. supported.

* Add FS/File::stat and support POSIX stat/fstat

Author: earlephilhower

cores/rp2040/FS.cpp

@@ -225,6 +225,21 @@ void File::setTimeCallback(time_t (*cb)(void)) {
     _timeCallback = cb;
 }
 
+bool File::stat(FSStat *st) {
+    if (!_p) {
+        return false;
+    }
+    size_t pos = position();
+    seek(0, SeekEnd);
+    st->size = position() - pos;
+    seek(pos, SeekSet);
+    st->blocksize = 0; // Not set here
+    st->ctime = getCreationTime();
+    st->atime = getLastWrite();
+    st->isDir = isDirectory();
+    return true;
+}
+
 File Dir::openFile(const char* mode) {
     if (!_impl) {
         return File();
@@ -455,6 +470,17 @@ bool FS::rename(const String& pathFrom, const String& pathTo) {
     return rename(pathFrom.c_str(), pathTo.c_str());
 }
 
+bool FS::stat(const char *path, FSStat *st) {
+    if (!_impl) {
+        return false;
+    }
+    return _impl->stat(path, st);
+}
+
+bool FS::stat(const String& path, FSStat *st) {
+    return stat(path.c_str(), st);
+}
+
 time_t FS::getCreationTime() {
     if (!_impl) {
         return 0;

cores/rp2040/FS.h

@@ -48,6 +48,14 @@ enum SeekMode {
     SeekEnd = 2
 };
 
+struct FSStat {
+    size_t size;
+    size_t blocksize;
+    time_t ctime;
+    time_t atime;
+    bool isDir;
+};
+
 class File : public Stream {
 public:
     File(FileImplPtr p = FileImplPtr(), FS *baseFS = nullptr) : _p(p), _fakeDir(nullptr), _baseFS(baseFS) {
@@ -119,6 +127,8 @@ class File : public Stream {
     time_t getCreationTime();
     void setTimeCallback(time_t (*cb)(void));
 
+    bool stat(FSStat *st);
+
 protected:
     FileImplPtr _p;
     time_t (*_timeCallback)(void) = nullptr;
@@ -212,6 +222,9 @@ class FS {
     bool rmdir(const char* path);
     bool rmdir(const String& path);
 
+    bool stat(const char *path, FSStat *st);
+    bool stat(const String& path, FSStat *st);
+
     // Low-level FS routines, not needed by most applications
     bool gc();
     bool check();

cores/rp2040/FSImpl.h

@@ -126,6 +126,7 @@ class FSImpl {
     virtual bool remove(const char* path) = 0;
     virtual bool mkdir(const char* path) = 0;
     virtual bool rmdir(const char* path) = 0;
+    virtual bool stat(const char *path, FSStat *st) = 0;
     virtual bool gc() {
         return true;    // May not be implemented in all file systems.
     }

docs/fs.rst

@@ -151,6 +151,48 @@ second SPI port, ``SPI1``.  Just use the following call in place of
     SD.begin(cspin, SPI1);
 
 
+Using VFS (Virtual File System) for POSIX support
+-------------------------------------------------
+The ``VFS`` library enables sketches to use standard POSIX file I/O operations using
+standard ``FILE *`` operations.  Include the ``VFS`` library in your application and
+add a call to map the ``VFS.root()`` to your filesystem.  I.e.:
+
+.. code:: cpp
+
+    #include <VFS.h>
+    #include <LittleFS.h>
+
+    void setup() {
+      LittleFS.begin();
+      VFS.root(LittleFS);
+      FILE *fp = fopen("/thisfilelivesonflash.txt", "w");
+      fprintf(fp, "Hello!\n");
+      fclose(fp);
+    }
+
+Multiple filesystems can be ``VFS.map()`` into the VFS namespace under different directory
+names.  For example, the following will make files on ``/sd`` reside on an external\
+SD card and files on ``/lfs`` live in internal flash.
+
+.. code:: cpp
+
+    #include <VFS.h>
+    #include <LittleFS.h>
+    #include <SDFS.h>
+
+    void setup() {
+      LittleFS.begin();
+      SDFS.begin();
+      VFS.map("/lfs", LittleFS);
+      VFS.map("/sd", SDFS);
+      FILE *onSD = fopen("/sd/thislivesonsd.txt", "wb");
+      ....
+    }
+
+See the examples in the ``VFS`` library for more information.
+
+
+
 File system object (LittleFS/SD/SDFS/FatFS)
 -------------------------------------------
 

libraries/FatFS/src/FatFS.h

@@ -117,6 +117,26 @@ class FatFSImpl : public FSImpl {
         return _mounted ? (FR_OK == f_unlink(path)) : false;
     }
 
+    bool stat(const char *path, FSStat *st) override {
+        if (!_mounted || !path || !path[0]) {
+            return false;
+        }
+        bzero(st, sizeof(*st));
+        FILINFO fno;
+        if (FR_OK != f_stat(path, &fno)) {
+            return false;
+        }
+        st->size = fno.fsize;
+        st->blocksize = 0;
+        st->isDir = (fno.fattrib & AM_DIR) == AM_DIR;
+        if (st->isDir) {
+            st->size = 0;
+        }
+        st->ctime = FatToTimeT(fno.fdate, fno.ftime);
+        st->atime = FatToTimeT(fno.fdate, fno.ftime);
+        return true;
+    }
+
     bool setConfig(const FSConfig &cfg) override {
         if ((cfg._type != FatFSConfig::FSId) || _mounted) {
             DEBUGV("FatFS::setConfig: invalid config or already mounted\n");

libraries/LittleFS/src/LittleFS.h

@@ -237,6 +237,27 @@ class LittleFSImpl : public FSImpl {
         return true;
     }
 
+    bool stat(const char *path, FSStat *st) override {
+        if (!_mounted || !path || !path[0]) {
+            return false;
+        }
+        lfs_info info;
+        if (lfs_stat(&_lfs, path, &info) < 0) {
+            return false;
+        }
+        st->size = info.size;
+        st->blocksize = _blockSize;
+        st->isDir = info.type == LFS_TYPE_DIR;
+        if (st->isDir) {
+            st->size = 0;
+        }
+        if (lfs_getattr(&_lfs, path, 'c', (void *)&st->ctime, sizeof(st->ctime)) != sizeof(st->ctime)) {
+            st->ctime = 0;
+        }
+        st->atime = st->ctime;
+        return true;
+    }
+
     time_t getCreationTime() override {
         time_t t;
         uint32_t t32b;

libraries/SDFS/src/SDFS.h

@@ -148,6 +148,34 @@ class SDFSImpl : public FSImpl {
 
     bool format() override;
 
+    bool stat(const char *path, FSStat *st) override {
+        if (!_mounted || !path || !path[0]) {
+            return false;
+        }
+        bzero(st, sizeof(*st));
+        File32 f;
+        f = _fs.open(path, O_RDONLY);
+        if (!f) {
+            return false;
+        }
+        st->size = f.fileSize();
+        st->blocksize = clusterSize();
+        st->isDir = f.isDir();
+        if (st->isDir) {
+            st->size = 0;
+        }
+        uint16_t date;
+        uint16_t time;
+        if (f.getCreateDateTime(&date, &time)) {
+            st->ctime = FatToTimeT(date, time);
+        }
+        if (f.getAccessDate(&date)) {
+            st->atime = FatToTimeT(date, 0);
+        }
+        f.close();
+        return true;
+    }
+
     // The following are not common FS interfaces, but are needed only to
     // support the older SD.h exports
     uint8_t type() {

libraries/VFS/examples/VFSMultipleMounts/VFSMultipleMounts.ino

@@ -0,0 +1,114 @@
+// Released to the piublic domain by Earle F. Philhower, III in 2024
+
+#include <LittleFS.h>
+#include <VFS.h>
+#include <SPI.h>
+#include <SDFS.h>
+
+// This are GP pins for SPI0 on the Raspberry Pi Pico board, and connect
+// to different *board* level pinouts.  Check the PCB while wiring.
+// Only certain pins can be used by the SPI hardware, so if you change
+// these be sure they are legal or the program will crash.
+// See: https://datasheets.raspberrypi.com/picow/PicoW-A4-Pinout.pdf
+const int _MISO = 4;  // AKA SPI RX
+const int _MOSI = 7;  // AKA SPI TX
+const int _CS = 5;
+const int _SCK = 6;
+// SPI1
+//const int _MISO = 8;  // AKA SPI RX
+//const int _MOSI = 11;  // AKA SPI TX
+//const int _CS = 9;
+//const int _SCK = 10;
+
+void setup() {
+  delay(5000);
+  if (!LittleFS.begin()) {
+    Serial.printf("ERROR: Unable to start LittleFS. Did you select a filesystem size in the menus?\n");
+    return;
+  }
+
+  SDFSConfig cfg;
+  bool sd = false;
+  if (_MISO == 0 || _MISO == 4 || _MISO == 16) {
+    SPI.setRX(_MISO);
+    SPI.setTX(_MOSI);
+    SPI.setSCK(_SCK);
+    SDFS.setConfig(SDFSConfig(_CS, SPI_HALF_SPEED, SPI));
+    sd = SDFS.begin();
+  } else if (_MISO == 8 || _MISO == 12) {
+    SPI1.setRX(_MISO);
+    SPI1.setTX(_MOSI);
+    SPI1.setSCK(_SCK);
+    SDFS.setConfig(SDFSConfig(_CS, SPI_HALF_SPEED, SPI1));
+    sd = SDFS.begin();
+  } else {
+    Serial.println(F("ERROR: Unknown SPI Configuration"));
+  }
+
+  VFS.map("/lfs", LittleFS); // Onboard flash at /lfs
+  if (sd) {
+    VFS.map("/sd", SDFS); // SD card mapped to /sd
+  }
+  VFS.root(LittleFS); // Anything w/o a prefix maps to LittleFS
+
+  Serial.printf("Writing to /lfs/text.txt\n");
+  FILE *f = fopen("/lfs/text.txt", "wb");
+  fwrite("hello littlefs", 14, 1, f);
+  fclose(f);
+
+  if (sd) {
+    Serial.printf("Writing to /sd/test.txt, should not overwrite /lfs/text.txt!\n");
+    f = fopen("/sd/text.txt", "wb");
+    fwrite("hello sdfs", 10, 1, f);
+    fclose(f);
+  }
+
+  f = fopen("/lfs/text.txt", "rb");
+  char buff[33];
+  bzero(buff, 33);
+  fread(buff, 1, 32, f);
+  fclose(f);
+  Serial.printf("READ LFS> '%s'\n", buff);
+
+  if (sd) {
+    f = fopen("/sd/text.txt", "rb");
+    bzero(buff, 33);
+    fread(buff, 1, 32, f);
+    fclose(f);
+    Serial.printf("READ SDFS> '%s'\n", buff);
+  }
+
+  f = fopen("/text.txt", "rb");
+  bzero(buff, 33);
+  fread(buff, 1, 32, f);
+  fclose(f);
+  Serial.printf("READ default FS (LittleFS)> '%s'\n", buff);
+
+  Serial.printf("\nTesting seeking within a file\n");
+  f = fopen("/lfs/text.txt", "rb");
+  for (int i = 0; i < 10; i ++) {
+    fseek(f, i, SEEK_SET);
+    bzero(buff, 33);
+    fread(buff, 1, 32, f);
+    Serial.printf("LFS SEEK %d> '%s'\n", i, buff);
+  }
+  fclose(f);
+
+  Serial.printf("\nTesting fprintf and fgetc from LFS\n");
+  f = fopen("/lfs/printout.txt", "w");
+  for (int i = 0; i < 10; i++) {
+    fprintf(f, "INT: %d\n", i);
+  }
+  fclose(f);
+
+  Serial.printf("----\n");
+  f = fopen("/printout.txt", "r");
+  int x;
+  while ((x = fgetc(f)) >= 0) {
+    Serial.printf("%c", x);
+  }
+  Serial.printf("----\n");
+}
+
+void loop() {
+}

libraries/VFS/keywords.txt

@@ -0,0 +1,22 @@
+#######################################
+# Syntax Coloring Map
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+VFS	KEYWORD1
+FILE	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+
+map	KEYWORD1
+root	KEYWORD1
+
+#######################################
+# Constants (LITERAL1)
+#######################################
+

libraries/VFS/library.properties

@@ -0,0 +1,10 @@
+name=VFS
+version=1.0
+author=Earle F. Philhower, III <[email protected]>
+maintainer=Earle F. Philhower, III <[email protected]>
+sentence=Use POSIX fopen/etc. with Arduino filesystems like LittleFS, SD, etc.
+paragraph=Use POSIX fopen/etc. with Arduino filesystems like LittleFS, SD, etc.
+category=Data Storage
+url=https://gifhub.com/earlephilhower/arduino-pico
+architectures=rp2040
+dot_a_linkage=true