Added some comments over lfs_config's fragment_size/crystal_thresh/etc

Also added related asserts to lfs_init.

Note the fragment_size <= block_size/8 limit is to avoid wasteful corner
cases where only one fragment can fit in a block. The shrub_size <=
block_size/4 limit is looser because of how shrubs temporarily
overcommit.

As for the other limits, inline_size is bounded by shrub_size, and
crystal_thresh technically doesn't have a limit, though values >
block_size stop having an effect.

lfs.c

@@ -15227,6 +15227,12 @@ static int lfs_init(lfs_t *lfs, const struct lfs_config *cfg) {
     // wear-leveling.
     LFS_ASSERT(lfs->cfg->block_cycles != 0);
 
+    // inline_size must be <= block_size/4
+    LFS_ASSERT(lfs->cfg->inline_size <= lfs->cfg->block_size/4);
+    // shrub_size must be <= block_size/4
+    LFS_ASSERT(lfs->cfg->shrub_size <= lfs->cfg->block_size/4);
+    // fragment_size must be <= block_size/8
+    LFS_ASSERT(lfs->cfg->fragment_size <= lfs->cfg->block_size/8);
 
     // setup read cache
     lfs->rcache.block = 0;

lfs.h

@@ -267,10 +267,34 @@ struct lfs_config {
 //    // Defaults to block_size when zero.
 //    lfs_size_t metadata_max;
 
-    // TODO document
+    // TODO these are pretty low-level details, should we have reasonable
+    // defaults? need to benchmark.
+
+    // Maximum size on inlined files in bytes. Inlined files decrease storage
+    // requirements, but may impact metadata-related performance. Must be <=
+    // block_size/4.
+    //
+    // 0 disables inline files.
     lfs_size_t inline_size;
+
+    // Maximum size of inlined trees (shrubs) in bytes. Shrubs reduce B-tree
+    // root overhead, but may impact metadata-related performance. Must be <=
+    // blocksize/4.
+    //
+    // 0 disables shrubs.
     lfs_size_t shrub_size;
+
+    // Maximum size of a non-block B-tree leaf in bytes. Smaller values may
+    // make small random-writes cheaper, but increase metadata overhead. Must
+    // be <= block_size/8.
     lfs_size_t fragment_size;
+
+    // Threshold for compacting multiple fragments into a block. Smaller
+    // values will compact more frequently, reducing disk usage, but
+    // increasing the cost of random-writes.
+    //
+    // 0 only writes blocks, minimizing disk usage, while -1 or any value >=
+    // block_size only writes fragments, minimizing random-write cost.
     lfs_size_t crystal_thresh;
 };
 

runners/bench_runner.h

@@ -119,7 +119,7 @@ void bench_permutation(size_t i, uint32_t *buffer, size_t size);
         lfs_max(16, lfs_max(READ_SIZE, PROG_SIZE))) \
     BENCH_DEFINE(INLINE_SIZE,        BLOCK_SIZE/4                           ) \
     BENCH_DEFINE(SHRUB_SIZE,         INLINE_SIZE                            ) \
-    BENCH_DEFINE(FRAGMENT_SIZE,      CACHE_SIZE                             ) \
+    BENCH_DEFINE(FRAGMENT_SIZE,      BLOCK_SIZE/8                           ) \
     BENCH_DEFINE(CRYSTAL_THRESH,     BLOCK_SIZE/8                           ) \
     BENCH_DEFINE(LOOKAHEAD_SIZE,     16                                     ) \
     BENCH_DEFINE(BLOCK_CYCLES,       -1                                     ) \

runners/test_runner.h

@@ -103,7 +103,7 @@ void test_permutation(size_t i, uint32_t *buffer, size_t size);
         lfs_max(16, lfs_max(READ_SIZE, PROG_SIZE))                          ) \
     TEST_DEFINE(INLINE_SIZE,        BLOCK_SIZE/4                            ) \
     TEST_DEFINE(SHRUB_SIZE,         INLINE_SIZE                             ) \
-    TEST_DEFINE(FRAGMENT_SIZE,      CACHE_SIZE                              ) \
+    TEST_DEFINE(FRAGMENT_SIZE,      BLOCK_SIZE/8                            ) \
     TEST_DEFINE(CRYSTAL_THRESH,     BLOCK_SIZE/8                            ) \
     TEST_DEFINE(LOOKAHEAD_SIZE,     16                                      ) \
     TEST_DEFINE(BLOCK_CYCLES,       -1                                      ) \