.

include/wendelin/bigfile/file.h

@@ -20,13 +20,17 @@
  *
  * See COPYING file for full licensing terms.
  * See https://www.nexedi.com/licensing for rationale and options.
+ */
+
+/* Header wendelin/bigfile/file.h provides BigFile and interfaces that
+ * particular BigFile implementations must provide.
  *
- * ~~~~~~~~
- *
- * TODO description
+ * The interfaces are described in `struct bigfile_ops`.
+ * A particular BigFile implementation must provide loadblk/storeblk and
+ * optionally mmap_* methods.
  *
- * Clients usually work with bigfiles via mapping files to memory -
- * see wendelin/bigfile/virtmem.h and BigFileH for details. XXX
+ * Clients work with bigfiles via mapping files to memory - see
+ * wendelin/bigfile/virtmem.h and BigFileH for client-level API details.
  */
 
 #include <stddef.h>
@@ -42,7 +46,7 @@ typedef struct VMA VMA;
 /* BigFile base class
  *
  * BigFile is a file of fixed size blocks. It knows how to load/store blocks
- * to/from memory. Nothing else.    XXX also mmap?
+ * to/from memory. It can be also optionally memory mmaped.
  *
  * Concrete file implementations subclass BigFile and define their file_ops.
  */
@@ -80,32 +84,37 @@ struct bigfile_ops {
     void (*release)  (BigFile *file);
 
 
-    // Overlaying
-    //
-    // XXX text
-
-    // wc mmap =
-    //
-    //                  ┌──┐                      ┌──┐
-    //                  │RW│                      │RW│      ← dirty
-    //                  └──┘                      └──┘
-    //                            +
-    //      ─────────────────────────────────────────────   ← base
-    //
-    // base = file view @ zconn.at  =>
-    // base =
-    //                                           ___        /@revA/bigfile/X
-    //         __                                           /@revB/bigfile/X
-    //                _                                     /@revC/bigfile/X
-    //                            +                         ...
-    //      ───  ───── ──────────────────────────   ─────   /head/bigfile/X
-    //
-    // XXX link to wcfs/client/wcfs.h
-
-    // - mmap_setup_read(vma, file[blk +blklen)) -> addr    setup initial read-only mmap to serve vma
-    // - remmap_blk_read(vma, file[blk])            remmap blk into vma again, after e.g.
-    //                                              RW dirty page was discarded
-    // - munmap(vma)                                before VMA is unmapped
+    /* Mmap overlaying
+     *
+     * Besides .loadblk and .storeblk a particular BigFile implementation can
+     * also optionally provide functions to setup read-only memory mappings
+     * with BigFile data. If such functions are provided, virtmem might use
+     * them to organize read access to BigFile data through the mappings and
+     * without allocating RAM for read pages. RAM will still be allocated for
+     * dirtied pages that are layed over base data layer provided by the
+     * mappings.
+     *
+     * The major user of this functionality is wcfs - virtual filesystem that
+     * provides access to ZBigFile data via OS-level files(*). The layering can be
+     * schematically depicted as follows
+     *
+     *                  ┌──┐                      ┌──┐
+     *                  │RW│                      │RW│      ← dirty pages
+     *                  └──┘                      └──┘
+     *                            +
+     *      ─────────────────────────────────────────────   ← mmap'ed base data
+     *
+     * The functions to setup memory mappings are:
+     *
+     *   - mmap_setup_read(vma, file[blk +blklen)) -> addr    setup initial read-only mmap to serve vma
+     *   - remmap_blk_read(vma, file[blk])            remmap blk into vma again, after e.g.
+     *                                                RW dirty page was discarded
+     *   - munmap(vma)                                before VMA is unmapped
+     *
+     *
+     * (*) see wcfs/client/wcfs.h
+     */
+
 
     /* mmap_setup_read is called to setup new read-only mapping of file[blk +blklen).
      *
@@ -140,12 +149,13 @@ struct bigfile_ops {
     void* (*mmap_setup_read) (VMA *vma, BigFile *file, blk_t blk, size_t blklen);
 
 
-    // remmap_blk_read is called to remmap a block into vma again, after e.g.
-    // RW dirty page was discarded.
-    //
-    // Called under virtmem lock.       NOTE hard to rework to call with !virt_lock
-    //
-    // XXX error -> bug (must not fail)
+    /* remmap_blk_read is called to remmap a block into vma again, after e.g.
+     * RW dirty page was discarded.
+     *
+     * Called under virtmem lock.       NOTE hard to rework to call with !virt_lock
+     *
+     * XXX error -> bug (must not fail)
+     */
     int (*remmap_blk_read) (VMA *vma, BigFile *file, blk_t blk);
 
     /* munmap is called when vma set up via mmap_setup_read is going to be unmapped.

include/wendelin/bigfile/virtmem.h

@@ -30,7 +30,19 @@
  * marks modified pages as dirty. Dirty pages then can be on request either
  * written out back to file or discarded.
  *
- * XXX update for wcfs.
+ *
+ * Mmap overlaying
+ *
+ * A particular BigFile implementation can optionally provide functionality to
+ * mmap its data into memory. For BigFile handles opened in such mode, virtmem
+ * does not allocate RAM for read access and will only allocate RAM when pages
+ * are dirtied. The mode in which BigFile handle is opened is specified via
+ * fileh_open(flags=...).
+ *
+ * The major user of "mmap overlay" functionality is wcfs - virtual filesystem
+ * that provides access to ZBigFile data via OS-level files(*).
+ *
+ * (*) see wcfs/client/wcfs.h and wcfs/wcfs.go
  */
 
 #include <stdint.h>