micropython · dpgeorge · Oct 29, 2019 · Sep 7, 2019 · Sep 8, 2019 · Oct 18, 2019
diff --git a/docs/library/uos.rst b/docs/library/uos.rst
@@ -187,25 +187,51 @@ implementation of this class will usually allow access to the memory-like
 functionality a piece of hardware (like flash memory).  A block device can be
 used by a particular filesystem driver to store the data for its filesystem.
 
+There are two compatible signatures for the ``readblocks`` and ``writeblocks``
+methods (see below), in order to support a variety of use cases.  A given block
+device may implement one form or the other, or both at the same time.
+
 .. class:: AbstractBlockDev(...)
 
     Construct a block device object.  The parameters to the constructor are
     dependent on the specific block device.
 
     .. method:: readblocks(block_num, buf)
+    .. method:: readblocks(block_num, buf, offset)
 
+        The first form reads aligned, multiples of blocks.
         Starting at the block given by the index *block_num*, read blocks from
         the device into *buf* (an array of bytes).
         The number of blocks to read is given by the length of *buf*,
         which will be a multiple of the block size.
 
+        The second form allows reading at arbitrary locations within a block,
+        and arbitrary lengths.
+        Starting at block index *block_num*, and byte offset within that block
+        of *offset*, read bytes from the device into *buf* (an array of bytes).
+        The number of bytes to read is given by the length of *buf*.
+
     .. method:: writeblocks(block_num, buf)
+    .. method:: writeblocks(block_num, buf, offset)
 
+        The first form writes aligned, multiples of blocks, and requires that the
+        blocks that are written to be first erased (if necessary) by this method.
         Starting at the block given by the index *block_num*, write blocks from
         *buf* (an array of bytes) to the device.
         The number of blocks to write is given by the length of *buf*,
         which will be a multiple of the block size.
 
+        The second form allows writing at arbitrary locations within a block,
+        and arbitrary lengths.  Only the bytes being written should be changed,
+        and the caller of this method must ensure that the relevant blocks are
+        erased via a prior ``ioctl`` call.
+        Starting at block index *block_num*, and byte offset within that block
+        of *offset*, write bytes from *buf* (an array of bytes) to the device.
+        The number of bytes to write is given by the length of *buf*.
+
+        Note that implementations must never implicitly erase blocks if the offset
+        argument is specified, even if it is zero.
+
     .. method:: ioctl(op, arg)
 
         Control the block device and query its parameters.  The operation to
@@ -219,6 +245,7 @@ used by a particular filesystem driver to store the data for its filesystem.
           - 5 -- get the number of bytes in a block, should return an integer,
             or ``None`` in which case the default value of 512 is used
             (*arg* is unused)
+          - 6 -- erase a block, *arg* is the block number to erase
 
 By way of example, the following class will implement a block device that stores
 its data in RAM using a ``bytearray``::
@@ -250,3 +277,34 @@ It can be used as follows::
     uos.VfsFat.mkfs(bdev)
     vfs = uos.VfsFat(bdev)
     uos.mount(vfs, '/ramdisk')
+
+An example of a block device that supports both signatures and behaviours of
+the :meth:`readblocks` and :meth:`writeblocks` methods is::
+
+    class RAMBlockDev:
+        def __init__(self, block_size, num_blocks):
+            self.block_size = block_size
+            self.data = bytearray(block_size * num_blocks)
+
+        def readblocks(self, block, buf, offset=0):
+            addr = block_num * self.block_size + offset
+            for i in range(len(buf)):
+                buf[i] = self.data[addr + i]
+
+        def writeblocks(self, block_num, buf, offset=None):
+            if offset is None:
+                # do erase, then write
+                for i in range(len(buf) // self.block_size):
+                    self.ioctl(6, block_num + i)
+                offset = 0
+            addr = block_num * self.block_size + offset
+            for i in range(len(buf)):
+                self.data[addr + i] = buf[i]
+
+        def ioctl(self, op, arg):
+            if op == 4: # block count
+                return len(self.data) // self.block_size
+            if op == 5: # block size
+                return self.block_size
+            if op == 6: # block erase
+                return 0
diff --git a/extmod/extmod.mk b/extmod/extmod.mk
@@ -3,6 +3,22 @@
 # this sets the config file for FatFs
 CFLAGS_MOD += -DFFCONF_H=\"lib/oofatfs/ffconf.h\"
 
+################################################################################
+# VFS littlefs
+
+ifeq ($(MICROPY_VFS_LFS),1)
+CFLAGS_MOD += -DMICROPY_VFS_LFS=1
+CFLAGS_MOD += -DLFS1_NO_MALLOC -DLFS1_NO_DEBUG -DLFS1_NO_WARN -DLFS1_NO_ERROR -DLFS1_NO_ASSERT
+CFLAGS_MOD += -DLFS2_NO_MALLOC -DLFS2_NO_DEBUG -DLFS2_NO_WARN -DLFS2_NO_ERROR -DLFS2_NO_ASSERT
+LITTLEFS_DIR = lib/littlefs
+SRC_MOD += $(addprefix $(LITTLEFS_DIR)/,\
+	lfs1.c \
+	lfs1_util.c \
+	lfs2.c \
+	lfs2_util.c \
+	)
+endif
+
 ################################################################################
 # ussl
 

diff --git a/extmod/vfs.h b/extmod/vfs.h
@@ -38,25 +38,54 @@
 #define MP_S_IFDIR (0x4000)
 #define MP_S_IFREG (0x8000)
 
+// these are the values for mp_vfs_blockdev_t.flags
+#define MP_BLOCKDEV_FLAG_NATIVE         (0x0001) // readblocks[2]/writeblocks[2] contain native func
+#define MP_BLOCKDEV_FLAG_FREE_OBJ       (0x0002) // fs_user_mount_t obj should be freed on umount
+#define MP_BLOCKDEV_FLAG_HAVE_IOCTL     (0x0004) // new protocol with ioctl
+#define MP_BLOCKDEV_FLAG_NO_FILESYSTEM  (0x0008) // the block device has no filesystem on it
+
 // constants for block protocol ioctl
-#define BP_IOCTL_INIT           (1)
-#define BP_IOCTL_DEINIT         (2)
-#define BP_IOCTL_SYNC           (3)
-#define BP_IOCTL_SEC_COUNT      (4)
-#define BP_IOCTL_SEC_SIZE       (5)
+#define MP_BLOCKDEV_IOCTL_INIT          (1)
+#define MP_BLOCKDEV_IOCTL_DEINIT        (2)
+#define MP_BLOCKDEV_IOCTL_SYNC          (3)
+#define MP_BLOCKDEV_IOCTL_BLOCK_COUNT   (4)
+#define MP_BLOCKDEV_IOCTL_BLOCK_SIZE    (5)
+#define MP_BLOCKDEV_IOCTL_BLOCK_ERASE   (6)
 
 // 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);
 } mp_vfs_proto_t;
 
+typedef struct _mp_vfs_blockdev_t {
+    uint16_t flags;
+    size_t block_size;
+    mp_obj_t readblocks[5];
+    mp_obj_t writeblocks[5];
+    // new protocol uses just ioctl, old uses sync (optional) and count
+    union {
+        mp_obj_t ioctl[4];
+        struct {
+            mp_obj_t sync[2];
+            mp_obj_t count[2];
+        } old;
+    } u;
+} mp_vfs_blockdev_t;
+
 typedef struct _mp_vfs_mount_t {
     const char *str; // mount point with leading /
     size_t len;
     mp_obj_t obj;
     struct _mp_vfs_mount_t *next;
 } mp_vfs_mount_t;
 
+void mp_vfs_blockdev_init(mp_vfs_blockdev_t *self, mp_obj_t bdev);
+int mp_vfs_blockdev_read(mp_vfs_blockdev_t *self, size_t block_num, size_t num_blocks, uint8_t *buf);
+int mp_vfs_blockdev_read_ext(mp_vfs_blockdev_t *self, size_t block_num, size_t block_off, size_t len, uint8_t *buf);
+int mp_vfs_blockdev_write(mp_vfs_blockdev_t *self, size_t block_num, size_t num_blocks, const uint8_t *buf);
+int mp_vfs_blockdev_write_ext(mp_vfs_blockdev_t *self, size_t block_num, size_t block_off, size_t len, const uint8_t *buf);
+mp_obj_t mp_vfs_blockdev_ioctl(mp_vfs_blockdev_t *self, uintptr_t cmd, uintptr_t arg);
+
 mp_vfs_mount_t *mp_vfs_lookup_path(const char *path, const char **path_out);
 mp_import_stat_t mp_vfs_import_stat(const char *path);
 mp_obj_t mp_vfs_mount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args);

diff --git a/extmod/vfs_blockdev.c b/extmod/vfs_blockdev.c
@@ -0,0 +1,143 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2013-2019 Damien P. George
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "py/runtime.h"
+#include "py/binary.h"
+#include "py/objarray.h"
+#include "py/mperrno.h"
+#include "extmod/vfs.h"
+
+#if MICROPY_VFS
+
+void mp_vfs_blockdev_init(mp_vfs_blockdev_t *self, mp_obj_t bdev) {
+    mp_load_method(bdev, MP_QSTR_readblocks, self->readblocks);
+    mp_load_method_maybe(bdev, MP_QSTR_writeblocks, self->writeblocks);
+    mp_load_method_maybe(bdev, MP_QSTR_ioctl, self->u.ioctl);
+    if (self->u.ioctl[0] != MP_OBJ_NULL) {
+        // Device supports new block protocol, so indicate it
+        self->flags |= MP_BLOCKDEV_FLAG_HAVE_IOCTL;
+    } else {
+        // No ioctl method, so assume the device uses the old block protocol
+        mp_load_method_maybe(bdev, MP_QSTR_sync, self->u.old.sync);
+        mp_load_method(bdev, MP_QSTR_count, self->u.old.count);
+    }
+}
+
+int mp_vfs_blockdev_read(mp_vfs_blockdev_t *self, size_t block_num, size_t num_blocks, uint8_t *buf) {
+    if (self->flags & MP_BLOCKDEV_FLAG_NATIVE) {
+        mp_uint_t (*f)(uint8_t*, uint32_t, uint32_t) = (void*)(uintptr_t)self->readblocks[2];
+        return f(buf, block_num, num_blocks);
+    } else {
+        mp_obj_array_t ar = {{&mp_type_bytearray}, BYTEARRAY_TYPECODE, 0, num_blocks * self->block_size, buf};
+        self->readblocks[2] = MP_OBJ_NEW_SMALL_INT(block_num);
+        self->readblocks[3] = MP_OBJ_FROM_PTR(&ar);
+        mp_call_method_n_kw(2, 0, self->readblocks);
+        // TODO handle error return
+        return 0;
+    }
+}
+
+int mp_vfs_blockdev_read_ext(mp_vfs_blockdev_t *self, size_t block_num, size_t block_off, size_t len, uint8_t *buf) {
+    mp_obj_array_t ar = {{&mp_type_bytearray}, BYTEARRAY_TYPECODE, 0, len, buf};
+    self->readblocks[2] = MP_OBJ_NEW_SMALL_INT(block_num);
+    self->readblocks[3] = MP_OBJ_FROM_PTR(&ar);
+    self->readblocks[4] = MP_OBJ_NEW_SMALL_INT(block_off);
+    mp_obj_t ret = mp_call_method_n_kw(3, 0, self->readblocks);
+    if (ret == mp_const_none) {
+        return 0;
+    } else {
+        return MP_OBJ_SMALL_INT_VALUE(ret);
+    }
+}
+
+int mp_vfs_blockdev_write(mp_vfs_blockdev_t *self, size_t block_num, size_t num_blocks, const uint8_t *buf) {
+    if (self->writeblocks[0] == MP_OBJ_NULL) {
+        // read-only block device
+        return -MP_EROFS;
+    }
+
+    if (self->flags & MP_BLOCKDEV_FLAG_NATIVE) {
+        mp_uint_t (*f)(const uint8_t*, uint32_t, uint32_t) = (void*)(uintptr_t)self->writeblocks[2];
+        return f(buf, block_num, num_blocks);
+    } else {
+        mp_obj_array_t ar = {{&mp_type_bytearray}, BYTEARRAY_TYPECODE, 0, num_blocks * self->block_size, (void*)buf};
+        self->writeblocks[2] = MP_OBJ_NEW_SMALL_INT(block_num);
+        self->writeblocks[3] = MP_OBJ_FROM_PTR(&ar);
+        mp_call_method_n_kw(2, 0, self->writeblocks);
+        // TODO handle error return
+        return 0;
+    }
+}
+
+int mp_vfs_blockdev_write_ext(mp_vfs_blockdev_t *self, size_t block_num, size_t block_off, size_t len, const uint8_t *buf) {
+    if (self->writeblocks[0] == MP_OBJ_NULL) {
+        // read-only block device
+        return -MP_EROFS;
+    }
+
+    mp_obj_array_t ar = {{&mp_type_bytearray}, BYTEARRAY_TYPECODE, 0, len, (void*)buf};
+    self->writeblocks[2] = MP_OBJ_NEW_SMALL_INT(block_num);
+    self->writeblocks[3] = MP_OBJ_FROM_PTR(&ar);
+    self->writeblocks[4] = MP_OBJ_NEW_SMALL_INT(block_off);
+    mp_obj_t ret = mp_call_method_n_kw(3, 0, self->writeblocks);
+    if (ret == mp_const_none) {
+        return 0;
+    } else {
+        return MP_OBJ_SMALL_INT_VALUE(ret);
+    }
+}
+
+mp_obj_t mp_vfs_blockdev_ioctl(mp_vfs_blockdev_t *self, uintptr_t cmd, uintptr_t arg) {
+    if (self->flags & MP_BLOCKDEV_FLAG_HAVE_IOCTL) {
+        // New protocol with ioctl
+        self->u.ioctl[2] = MP_OBJ_NEW_SMALL_INT(cmd);
+        self->u.ioctl[3] = MP_OBJ_NEW_SMALL_INT(arg);
+        return mp_call_method_n_kw(2, 0, self->u.ioctl);
+    } else {
+        // Old protocol with sync and count
+        switch (cmd) {
+            case MP_BLOCKDEV_IOCTL_SYNC:
+                if (self->u.old.sync[0] != MP_OBJ_NULL) {
+                    mp_call_method_n_kw(0, 0, self->u.old.sync);
+                }
+                break;
+
+            case MP_BLOCKDEV_IOCTL_BLOCK_COUNT:
+                return mp_call_method_n_kw(0, 0, self->u.old.count);
+
+            case MP_BLOCKDEV_IOCTL_BLOCK_SIZE:
+                // Old protocol has fixed sector size of 512 bytes
+                break;
+
+            case MP_BLOCKDEV_IOCTL_INIT:
+                // Old protocol doesn't have init
+                break;
+        }
+        return mp_const_none;
+    }
+}
+
+#endif // MICROPY_VFS
diff --git a/extmod/vfs_fat.c b/extmod/vfs_fat.c
@@ -68,27 +68,18 @@ STATIC mp_obj_t fat_vfs_make_new(const mp_obj_type_t *type, size_t n_args, size_
     // create new object
     fs_user_mount_t *vfs = m_new_obj(fs_user_mount_t);
     vfs->base.type = type;
-    vfs->flags = FSUSER_FREE_OBJ;
     vfs->fatfs.drv = vfs;
 
-    // load block protocol methods
-    mp_load_method(args[0], MP_QSTR_readblocks, vfs->readblocks);
-    mp_load_method_maybe(args[0], MP_QSTR_writeblocks, vfs->writeblocks);
-    mp_load_method_maybe(args[0], MP_QSTR_ioctl, vfs->u.ioctl);
-    if (vfs->u.ioctl[0] != MP_OBJ_NULL) {
-        // device supports new block protocol, so indicate it
-        vfs->flags |= FSUSER_HAVE_IOCTL;
-    } else {
-        // no ioctl method, so assume the device uses the old block protocol
-        mp_load_method_maybe(args[0], MP_QSTR_sync, vfs->u.old.sync);
-        mp_load_method(args[0], MP_QSTR_count, vfs->u.old.count);
-    }
+    // Initialise underlying block device
+    vfs->blockdev.flags = MP_BLOCKDEV_FLAG_FREE_OBJ;
+    vfs->blockdev.block_size = FF_MIN_SS; // default, will be populated by call to MP_BLOCKDEV_IOCTL_BLOCK_SIZE
+    mp_vfs_blockdev_init(&vfs->blockdev, args[0]);
 
     // mount the block device so the VFS methods can be used
     FRESULT res = f_mount(&vfs->fatfs);
     if (res == FR_NO_FILESYSTEM) {
         // don't error out if no filesystem, to let mkfs()/mount() create one if wanted
-        vfs->flags |= FSUSER_NO_FILESYSTEM;
+        vfs->blockdev.flags |= MP_BLOCKDEV_FLAG_NO_FILESYSTEM;
     } else if (res != FR_OK) {
         mp_raise_OSError(fresult_to_errno_table[res]);
     }
@@ -380,19 +371,19 @@ STATIC mp_obj_t vfs_fat_mount(mp_obj_t self_in, mp_obj_t readonly, mp_obj_t mkfs
     //  1. readonly=True keyword argument
     //  2. nonexistent writeblocks method (then writeblocks[0] == MP_OBJ_NULL already)
     if (mp_obj_is_true(readonly)) {
-        self->writeblocks[0] = MP_OBJ_NULL;
+        self->blockdev.writeblocks[0] = MP_OBJ_NULL;
     }
 
     // check if we need to make the filesystem
-    FRESULT res = (self->flags & FSUSER_NO_FILESYSTEM) ? FR_NO_FILESYSTEM : FR_OK;
+    FRESULT res = (self->blockdev.flags & MP_BLOCKDEV_FLAG_NO_FILESYSTEM) ? FR_NO_FILESYSTEM : FR_OK;
     if (res == FR_NO_FILESYSTEM && mp_obj_is_true(mkfs)) {
         uint8_t working_buf[FF_MAX_SS];
         res = f_mkfs(&self->fatfs, FM_FAT | FM_SFD, 0, working_buf, sizeof(working_buf));
     }
     if (res != FR_OK) {
         mp_raise_OSError(fresult_to_errno_table[res]);
     }
-    self->flags &= ~FSUSER_NO_FILESYSTEM;
+    self->blockdev.flags &= ~MP_BLOCKDEV_FLAG_NO_FILESYSTEM;
 
     return mp_const_none;
 }