From 0e6660d40f17212fc1dd67ef088791bf3ffa5d19 Mon Sep 17 00:00:00 2001
From: Christopher Haster <geky@geky.net>
Date: Sun, 18 Aug 2024 14:45:38 -0500
Subject: [PATCH] ckparity: Tweaked some comments

The main one being the lfsr_bd_readnext comment. lfsr_bd_readnext _can_
provide checked reads as long as we read the suffix first and use some
crc32c xor tricks:

1. Calculate c_s = crc32c(suffix)
2. Calculate c_p = crc32c(prefix)
3. Calculate c_d = crc32c(c_p, data)
4. Calculate crc = crc32c(c_d, suffix-sized zeros) xor c_s

There's probably some funny business with the init/fini xor, but you get
the idea.

Conveniently, we just never need to use a hypothetical
lfsr_bd_readnextck.

I was toying around with the idea of using lfsr_bd_readnextck to provide
better caching in the case our rcache is big (~= block_size), but it was
getting overly-complicated/problematic, so I'm dropping the idea for
now.
---
 lfs.c | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/lfs.c b/lfs.c
index e11386ae..46206c47 100644
--- a/lfs.c
+++ b/lfs.c
@@ -121,9 +121,6 @@ static inline void lfsr_bd_droppcache(lfs_t *lfs) {
 
 // caching read that lends you a buffer
 //
-// this fundamentally can't provide checked reads, so we really should
-// only use it to build other low-level bd functions
-//
 // note hint has two conveniences:
 //  0 => minimal caching
 // -1 => maximal caching
@@ -704,6 +701,7 @@ static int lfsr_bd_set(lfs_t *lfs, lfs_block_t block, lfs_size_t off,
 }
 
 
+
 /// lfsr_ck_t stuff ///
 
 #ifdef LFS_CKPARITY
@@ -753,6 +751,7 @@ static inline lfs_size_t lfsr_ck_ckoff(lfsr_ck_t ck) {
 }
 #endif
 
+
 // lfsr_tailck_t stuff
 //
 // tailck tracks the most recent trunk's parity so we can parity-check
@@ -784,9 +783,9 @@ static lfs_sbool_t lfsr_bd_readparity(lfs_t *lfs,
 
     // _usually_, the byte following a tag contains the tag's parity
     //
-    // but if we're in the middle of building a commit things get
-    // tricky since we may not have written this bit yet... this is why
-    // tailck exists, to track the most recent trunk's parity
+    // unless we're in the middle of building a commit, where things get
+    // tricky... to avoid problems with not-yet-written parity bits
+    // tailck tracks the most recent trunk's parity
     //
 
     // parity in in tailck?
@@ -808,6 +807,9 @@ static lfs_sbool_t lfsr_bd_readparity(lfs_t *lfs,
 }
 #endif
 
+
+// checked read functions
+
 #ifdef LFS_CKPARITY
 static lfs_ssize_t lfsr_bd_ckprefix(lfs_t *lfs,
         lfs_block_t block, lfs_size_t off, lfs_size_t hint,