micropython · dpgeorge · Mar 6, 2025 · Jan 3, 2025 · Nov 15, 2024 · Feb 20, 2025
diff --git a/docs/reference/mpremote.rst b/docs/reference/mpremote.rst
@@ -78,6 +78,7 @@ The full list of supported commands are:
 - `mip <mpremote_command_mip>`
 - `mount <mpremote_command_mount>`
 - `unmount <mpremote_command_unmount>`
+- `romfs <mpremote_command_romfs>`
 - `rtc <mpremote_command_rtc>`
 - `sleep <mpremote_command_sleep>`
 - `reset <mpremote_command_reset>`
@@ -347,6 +348,29 @@ The full list of supported commands are:
   This happens automatically when ``mpremote`` terminates, but it can be used
   in a sequence to unmount an earlier mount before subsequent command are run.
 
+.. _mpremote_command_romfs:
+
+- **romfs** -- manage ROMFS partitions on the device:
+
+  .. code-block:: bash
+
+      $ mpremote romfs <sub-command>
+
+  ``<sub-command>`` may be:
+
+  - ``romfs query`` to list all the available ROMFS partitions and their size
+  - ``romfs [-o <output>] build <source>`` to create a ROMFS image from the given
+    source directory; the default output file is the source appended by ``.romfs``
+  - ``romfs [-p <partition>] deploy <source>`` to deploy a ROMFS image to the device;
+    will also create a temporary ROMFS image if the source is a directory
+
+  The ``build`` and ``deploy`` sub-commands both support the ``-m``/``--mpy`` option
+  to automatically compile ``.py`` files to ``.mpy`` when creating the ROMFS image.
+  This option is enabled by default, but only works if the ``mpy_cross`` Python
+  package has been installed (eg via ``pip install mpy_cross``).  If the package is
+  not installed then a warning is printed and ``.py`` files remain as is.  Compiling
+  of ``.py`` files can be disabled with the ``--no-mpy`` option.
+
 .. _mpremote_command_rtc:
 
 - **rtc** -- set/get the device clock (RTC):

diff --git a/extmod/modvfs.c b/extmod/modvfs.c
@@ -38,11 +38,18 @@
 #error "MICROPY_PY_VFS requires MICROPY_VFS"
 #endif
 
+#if MICROPY_VFS_ROM_IOCTL
+static MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_vfs_rom_ioctl_obj, 1, 4, mp_vfs_rom_ioctl);
+#endif
+
 static const mp_rom_map_elem_t vfs_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_vfs) },
 
     { MP_ROM_QSTR(MP_QSTR_mount), MP_ROM_PTR(&mp_vfs_mount_obj) },
     { MP_ROM_QSTR(MP_QSTR_umount), MP_ROM_PTR(&mp_vfs_umount_obj) },
+    #if MICROPY_VFS_ROM_IOCTL
+    { MP_ROM_QSTR(MP_QSTR_rom_ioctl), MP_ROM_PTR(&mp_vfs_rom_ioctl_obj) },
+    #endif
     #if MICROPY_VFS_FAT
     { MP_ROM_QSTR(MP_QSTR_VfsFat), MP_ROM_PTR(&mp_fat_vfs_type) },
     #endif

diff --git a/extmod/vfs.c b/extmod/vfs.c
@@ -46,6 +46,10 @@
 #include "extmod/vfs_posix.h"
 #endif
 
+#if MICROPY_VFS_ROM && MICROPY_VFS_ROM_IOCTL
+#include "extmod/vfs_rom.h"
+#endif
+
 // For mp_vfs_proxy_call, the maximum number of additional args that can be passed.
 // A fixed maximum size is used to avoid the need for a costly variable array.
 #define PROXY_MAX_ARGS (2)
@@ -552,6 +556,32 @@ int mp_vfs_mount_and_chdir_protected(mp_obj_t bdev, mp_obj_t mount_point) {
     return ret;
 }
 
+#if MICROPY_VFS_ROM && MICROPY_VFS_ROM_IOCTL
+
+int mp_vfs_mount_romfs_protected(void) {
+    int ret;
+    nlr_buf_t nlr;
+    if (nlr_push(&nlr) == 0) {
+        mp_obj_t args[2] = { MP_OBJ_NEW_SMALL_INT(MP_VFS_ROM_IOCTL_GET_SEGMENT), MP_OBJ_NEW_SMALL_INT(0) };
+        mp_obj_t rom = mp_vfs_rom_ioctl(2, args);
+        mp_obj_t romfs = mp_call_function_1(MP_OBJ_FROM_PTR(&mp_type_vfs_rom), rom);
+        mp_obj_t mount_point = MP_OBJ_NEW_QSTR(MP_QSTR__slash_rom);
+        mp_call_function_2(MP_OBJ_FROM_PTR(&mp_vfs_mount_obj), romfs, mount_point);
+        #if MICROPY_PY_SYS_PATH_ARGV_DEFAULTS
+        // Add "/rom" and "/rom/lib" to `sys.path`.
+        mp_obj_list_append(mp_sys_path, MP_OBJ_NEW_QSTR(MP_QSTR__slash_rom));
+        mp_obj_list_append(mp_sys_path, MP_OBJ_NEW_QSTR(MP_QSTR__slash_rom_slash_lib));
+        #endif
+        ret = 0; // success
+        nlr_pop();
+    } else {
+        ret = -MP_EIO;
+    }
+    return ret;
+}
+
+#endif
+
 MP_REGISTER_ROOT_POINTER(struct _mp_vfs_mount_t *vfs_cur);
 MP_REGISTER_ROOT_POINTER(struct _mp_vfs_mount_t *vfs_mount_table);
 

diff --git a/extmod/vfs.h b/extmod/vfs.h
@@ -52,6 +52,13 @@
 #define MP_BLOCKDEV_IOCTL_BLOCK_SIZE    (5)
 #define MP_BLOCKDEV_IOCTL_BLOCK_ERASE   (6)
 
+// Constants for vfs.rom_ioctl() function.
+#define MP_VFS_ROM_IOCTL_GET_NUMBER_OF_SEGMENTS     (1) // rom_ioctl(1)
+#define MP_VFS_ROM_IOCTL_GET_SEGMENT                (2) // rom_ioctl(2, <id>)
+#define MP_VFS_ROM_IOCTL_WRITE_PREPARE              (3) // rom_ioctl(3, <id>, <len>)
+#define MP_VFS_ROM_IOCTL_WRITE                      (4) // rom_ioctl(4, <id>, <offset>, <buf>)
+#define MP_VFS_ROM_IOCTL_WRITE_COMPLETE             (5) // rom_ioctl(5, <id>)
+
 // At the moment the VFS protocol just has import_stat, but could be extended to other methods
 typedef struct _mp_vfs_proto_t {
     mp_import_stat_t (*import_stat)(void *self, const char *path);
@@ -105,6 +112,9 @@ mp_obj_t mp_vfs_stat(mp_obj_t path_in);
 mp_obj_t mp_vfs_statvfs(mp_obj_t path_in);
 
 int mp_vfs_mount_and_chdir_protected(mp_obj_t bdev, mp_obj_t mount_point);
+#if MICROPY_VFS_ROM && MICROPY_VFS_ROM_IOCTL
+int mp_vfs_mount_romfs_protected(void);
+#endif
 
 MP_DECLARE_CONST_FUN_OBJ_KW(mp_vfs_mount_obj);
 MP_DECLARE_CONST_FUN_OBJ_1(mp_vfs_umount_obj);
@@ -122,4 +132,12 @@ MP_DECLARE_CONST_FUN_OBJ_1(mp_vfs_rmdir_obj);
 MP_DECLARE_CONST_FUN_OBJ_1(mp_vfs_stat_obj);
 MP_DECLARE_CONST_FUN_OBJ_1(mp_vfs_statvfs_obj);
 
+#if MICROPY_VFS_ROM_IOCTL
+// When MICROPY_VFS_ROM_IOCTL is enabled a port must define the following function.
+// This is a generic interface to allow querying and modifying the user-accessible,
+// read-only memory area of a device, if it is configured with such an area.
+// Supported ioctl commands are given by MP_VFS_ROM_IOCTL_xxx.
+mp_obj_t mp_vfs_rom_ioctl(size_t n_args, const mp_obj_t *args);
+#endif
+
 #endif // MICROPY_INCLUDED_EXTMOD_VFS_H
diff --git a/ports/esp32/esp32_partition.c b/ports/esp32/esp32_partition.c
@@ -53,6 +53,20 @@ typedef struct _esp32_partition_obj_t {
     uint16_t block_size;
 } esp32_partition_obj_t;
 
+#if MICROPY_VFS_ROM_IOCTL
+
+static esp32_partition_obj_t esp32_partition_romfs_obj = {
+    .base = { .type = NULL },
+    .part = NULL,
+    .cache = NULL,
+    .block_size = NATIVE_BLOCK_SIZE_BYTES,
+};
+
+static const void *esp32_partition_romfs_ptr = NULL;
+static esp_partition_mmap_handle_t esp32_partition_romfs_handle;
+
+#endif
+
 static esp32_partition_obj_t *esp32_partition_new(const esp_partition_t *part, uint16_t block_size) {
     if (part == NULL) {
         mp_raise_OSError(MP_ENOENT);
@@ -114,6 +128,24 @@ static mp_obj_t esp32_partition_make_new(const mp_obj_type_t *type, size_t n_arg
     return MP_OBJ_FROM_PTR(esp32_partition_new(part, block_size));
 }
 
+#if MICROPY_VFS_ROM_IOCTL
+static mp_int_t esp32_partition_get_buffer(mp_obj_t self_in, mp_buffer_info_t *bufinfo, mp_uint_t flags) {
+    esp32_partition_obj_t *self = MP_OBJ_TO_PTR(self_in);
+    if (self == &esp32_partition_romfs_obj && flags == MP_BUFFER_READ) {
+        if (esp32_partition_romfs_ptr == NULL) {
+            check_esp_err(esp_partition_mmap(self->part, 0, self->part->size, ESP_PARTITION_MMAP_DATA, &esp32_partition_romfs_ptr, &esp32_partition_romfs_handle));
+        }
+        bufinfo->buf = (void *)esp32_partition_romfs_ptr;
+        bufinfo->len = self->part->size;
+        bufinfo->typecode = 'B';
+        return 0;
+    } else {
+        // Unsupported.
+        return 1;
+    }
+}
+#endif
+
 static mp_obj_t esp32_partition_find(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     // Parse args
     enum { ARG_type, ARG_subtype, ARG_label, ARG_block_size };
@@ -284,11 +316,55 @@ static const mp_rom_map_elem_t esp32_partition_locals_dict_table[] = {
 };
 static MP_DEFINE_CONST_DICT(esp32_partition_locals_dict, esp32_partition_locals_dict_table);
 
+#if MICROPY_VFS_ROM_IOCTL
+#define ESP32_PARTITION_GET_BUFFER buffer, esp32_partition_get_buffer,
+#else
+#define ESP32_PARTITION_GET_BUFFER
+#endif
+
 MP_DEFINE_CONST_OBJ_TYPE(
     esp32_partition_type,
     MP_QSTR_Partition,
     MP_TYPE_FLAG_NONE,
     make_new, esp32_partition_make_new,
     print, esp32_partition_print,
+    ESP32_PARTITION_GET_BUFFER
     locals_dict, &esp32_partition_locals_dict
     );
+
+/******************************************************************************/
+// romfs partition
+
+#if MICROPY_VFS_ROM_IOCTL
+
+mp_obj_t mp_vfs_rom_ioctl(size_t n_args, const mp_obj_t *args) {
+    if (esp32_partition_romfs_obj.base.type == NULL) {
+        esp32_partition_romfs_obj.base.type = &esp32_partition_type;
+        // Get the romfs partition.
+        // TODO: number of segments ioctl can be used if there is more than one romfs.
+        esp_partition_iterator_t iter = esp_partition_find(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, "romfs");
+        if (iter != NULL) {
+            esp32_partition_romfs_obj.part = esp_partition_get(iter);
+        }
+        esp_partition_iterator_release(iter);
+    }
+
+    switch (mp_obj_get_int(args[0])) {
+        case MP_VFS_ROM_IOCTL_GET_NUMBER_OF_SEGMENTS:
+            if (esp32_partition_romfs_obj.part == NULL) {
+                return MP_OBJ_NEW_SMALL_INT(0);
+            } else {
+                return MP_OBJ_NEW_SMALL_INT(1);
+            }
+        case MP_VFS_ROM_IOCTL_GET_SEGMENT:
+            if (esp32_partition_romfs_obj.part == NULL) {
+                return MP_OBJ_NEW_SMALL_INT(-MP_EINVAL);
+            } else {
+                return MP_OBJ_FROM_PTR(&esp32_partition_romfs_obj);
+            }
+        default:
+            return MP_OBJ_NEW_SMALL_INT(-MP_EINVAL);
+    }
+}
+
+#endif // MICROPY_VFS_ROM_IOCTL
diff --git a/ports/esp32/partitions-4MiB-romfs.csv b/ports/esp32/partitions-4MiB-romfs.csv
@@ -0,0 +1,8 @@
+# Notes: the offset of the partition table itself is set in
+# $IDF_PATH/components/partition_table/Kconfig.projbuild.
+# Name,   Type, SubType, Offset,  Size, Flags
+nvs,      data, nvs,     0x9000,  0x6000,
+phy_init, data, phy,     0xf000,  0x1000,
+factory,  app,  factory, 0x10000, 0x1D0000,
+romfs,    data, 0x8f,    0x1E0000, 0x20000,
+vfs,      data, fat,     0x200000, 0x200000,
diff --git a/ports/esp8266/Makefile b/ports/esp8266/Makefile
@@ -134,6 +134,7 @@ SRC_C = \
 	fatfs_port.c \
 	posix_helpers.c \
 	hspi.c \
+	vfs_rom_ioctl.c \
 	$(wildcard $(BOARD_DIR)/*.c) \
 
 ifeq ($(MICROPY_PY_ESPNOW),1)

diff --git a/ports/esp8266/boards/ESP8266_GENERIC/board.json b/ports/esp8266/boards/ESP8266_GENERIC/board.json
@@ -17,7 +17,8 @@
     "variants": {
         "OTA": "OTA compatible",
         "FLASH_1M": "1MiB flash",
-        "FLASH_512K": "512kiB flash"
+        "FLASH_512K": "512kiB flash",
+        "FLASH_2M_ROMFS": "2MiB flash with ROMFS"
     },
     "vendor": "Espressif"
 }
diff --git a/ports/esp8266/boards/ESP8266_GENERIC/mpconfigvariant_FLASH_2M_ROMFS.mk b/ports/esp8266/boards/ESP8266_GENERIC/mpconfigvariant_FLASH_2M_ROMFS.mk
@@ -0,0 +1,12 @@
+LD_FILES = boards/esp8266_2MiB_ROMFS.ld
+
+MICROPY_PY_ESPNOW ?= 1
+MICROPY_PY_BTREE ?= 1
+MICROPY_VFS_FAT ?= 1
+MICROPY_VFS_LFS2 ?= 1
+
+# Add asyncio and extra micropython-lib packages (in addition to the port manifest).
+FROZEN_MANIFEST ?= $(BOARD_DIR)/manifest_2MiB.py
+
+# Configure mpconfigboard.h.
+CFLAGS += -DMICROPY_ESP8266_2M -DMICROPY_VFS_ROM=1
diff --git a/ports/esp8266/boards/esp8266_2MiB_ROMFS.ld b/ports/esp8266/boards/esp8266_2MiB_ROMFS.ld
@@ -0,0 +1,24 @@
+/* GNU linker script for ESP8266 with 2M or more flash, and includes a ROMFS partition
+
+   Flash layout:
+    0x40200000 36k  header + iram/dram init
+    0x40209000 668k firmware (irom0)
+    0x402c0000 320k ROMFS
+    0x40300000 1M+  filesystem (not memory mapped)
+*/
+
+MEMORY
+{
+    dport0_0_seg : org = 0x3ff00000, len = 16
+    dram0_0_seg :  org = 0x3ffe8000, len = 80K
+    iram1_0_seg :  org = 0x40100000, len = 32K
+    irom0_0_seg :  org = 0x40209000, len = 1M - 36K - 320K
+    FLASH_ROMFS :  org = 0x402b0000, len = 320K
+}
+
+/* define ROMFS extents */
+_micropy_hw_romfs_start = ORIGIN(FLASH_ROMFS);
+_micropy_hw_romfs_size = LENGTH(FLASH_ROMFS);
+
+/* define common sections and symbols */
+INCLUDE boards/esp8266_common.ld
diff --git a/ports/esp8266/boards/esp8266_common.ld b/ports/esp8266/boards/esp8266_common.ld
@@ -170,6 +170,7 @@ SECTIONS
         *modonewire.o(.literal* .text*)
         *network_wlan.o(.literal* .text*)
         *esp_mphal.o(.literal* .text*)
+        *vfs_rom_ioctl.o(.literal* .text*)
 
         /* we put as much rodata as possible in this section */
         /* note that only rodata accessed as a machine word is allowed here */

diff --git a/ports/esp8266/modesp.c b/ports/esp8266/modesp.c
@@ -164,9 +164,16 @@ static MP_DEFINE_CONST_FUN_OBJ_0(esp_flash_size_obj, esp_flash_size);
 #define IS_OTA_FIRMWARE() ((*(uint32_t *)0x40200000 & 0xff00) == 0x100)
 
 extern byte _firmware_size[];
+#if MICROPY_VFS_ROM_IOCTL
+extern uint8_t _micropy_hw_romfs_size;
+#endif
 
 static mp_obj_t esp_flash_user_start(void) {
-    return MP_OBJ_NEW_SMALL_INT((uint32_t)_firmware_size);
+    uint32_t flash_user_start = (uint32_t)_firmware_size;
+    #if MICROPY_VFS_ROM_IOCTL
+    flash_user_start += (uint32_t)&_micropy_hw_romfs_size;
+    #endif
+    return MP_OBJ_NEW_SMALL_INT(flash_user_start);
 }
 static MP_DEFINE_CONST_FUN_OBJ_0(esp_flash_user_start_obj, esp_flash_user_start);