Added asserts on geometry and updated config documentation

littlefs had an unwritten assumption that the block device's program
size would be a multiple of the read size, and the block size would
be a multiple of the program size. This has already caused confusion
for users. Added a note and assert to catch unexpected geometries
early.

Also found that the prog/erase functions indicated they must return
LFS_ERR_CORRUPT to catch bad blocks. This is no longer true as errors
are found by CRC.

Author: geky

lfs.c

@@ -1926,6 +1926,10 @@ static int lfs_init(lfs_t *lfs, const struct lfs_config *cfg) {
         }
     }
 
+    // check that program and read sizes are multiples of the block size
+    assert(lfs->cfg->prog_size % lfs->cfg->read_size == 0);
+    assert(lfs->cfg->block_size % lfs->cfg->prog_size == 0);
+
     // check that the block size is large enough to fit ctz pointers
     assert(4*lfs_npw2(0xffffffff / (lfs->cfg->block_size-2*4))
             <= lfs->cfg->block_size);

lfs.h

@@ -99,14 +99,14 @@ struct lfs_config {
 
     // Program a region in a block. The block must have previously
     // been erased. Negative error codes are propogated to the user.
-    // The prog function must return LFS_ERR_CORRUPT if the block should
-    // be considered bad.
+    // May return LFS_ERR_CORRUPT if the block should be considered bad.
     int (*prog)(const struct lfs_config *c, lfs_block_t block,
             lfs_off_t off, const void *buffer, lfs_size_t size);
 
     // Erase a block. A block must be erased before being programmed.
     // The state of an erased block is undefined. Negative error codes
     // are propogated to the user.
+    // May return LFS_ERR_CORRUPT if the block should be considered bad.
     int (*erase)(const struct lfs_config *c, lfs_block_t block);
 
     // Sync the state of the underlying block device. Negative error codes
@@ -121,11 +121,13 @@ struct lfs_config {
     // Minimum size of a block program. This determines the size of program
     // buffers. This may be larger than the physical program size to improve
     // performance by caching more of the block device.
+    // Must be a multiple of the read size.
     lfs_size_t prog_size;
 
     // Size of an erasable block. This does not impact ram consumption and
     // may be larger than the physical erase size. However, this should be
-    // kept small as each file currently takes up an entire block .
+    // kept small as each file currently takes up an entire block.
+    // Must be a multiple of the program size.
     lfs_size_t block_size;
 
     // Number of erasable blocks on the device.