X wcfs/client: Overview += interaction with virtmem layer

wcfs/client/wcfs.h

@@ -32,8 +32,8 @@
 // views are a bit outdated, but close to head, which means that in practice
 // the kernel cache for /head/bigfile/* is being used almost 100% of the time.
 //
-// A mapping for bigfile X @at is built from OS-level memory mapping of on-WCFS
-// files as
+// A mapping for bigfile X @at is built from OS-level memory mappings of
+// on-WCFS files as
 //
 //                                           ___        /@revA/bigfile/X
 //         __                                           /@revB/bigfile/X
@@ -45,15 +45,6 @@
 // to maintain X@at data view according to WCFS invalidation protocol(*).
 //
 //
-// API overview
-//
-//  - `WCFS` represents filesystem-level connection to wcfs server.
-//  - `Conn` represents logical connection that provides view of data on wcfs
-//    filesystem as of particular database state.
-//  - `FileH` represent isolated file view under Conn.
-//  - `Mapping` represents one memory mapping of FileH.
-//
-//
 // Integration with wendelin.core virtmem layer
 //
 // This client package can be used standalone, but additionally provides
@@ -61,13 +52,36 @@
 // Mapping is created it can be associated as serving base layer for a
 // particular virtmem VMA via FileH.mmap(vma=...). In that case, since virtmem
 // itself adds another layer of dirty pages over read-only base provided by
-// Mapping(+), the Mapping will interact with virtmem layer to coordinate
+// Mapping
+//
+//                  ┌──┐                      ┌──┐
+//                  │RW│                      │RW│    ← virtmem VMA dirty pages
+//                  └──┘                      └──┘
+//                            +
+//                                                    VMA base = X@at view provided by Mapping:
+//
+//                                           ___        /@revA/bigfile/X
+//         __                                           /@revB/bigfile/X
+//                _                                     /@revC/bigfile/X
+//                            +                         ...
+//      ───  ───── ──────────────────────────   ─────   /head/bigfile/X
+//
+// the Mapping will interact with virtmem layer to coordinate
 // mapping memory updates.
 //
+//
+// API overview
+//
+//  - `WCFS` represents filesystem-level connection to wcfs server.
+//  - `Conn` represents logical connection that provides view of data on wcfs
+//    filesystem as of particular database state.
+//  - `FileH` represent isolated file view under Conn.
+//  - `Mapping` represents one memory mapping of FileH.
+//
+//
 // --------
 //
 // (*) see wcfs.go documentation for overview and details of WCFS isolation protocol.
-// (+) Mapping is already 2-layer as depicted above.
 
 #ifndef _NXD_WCFS_H_
 #define _NXD_WCFS_H_