Add image

docs/locking.md

@@ -25,4 +25,11 @@ Also, notice that this architecture allows for concurrency between FLUSHes and R
 ### The Flush State
 
 FLUSH operations need a potentially large amount of memory as their contextual state. To avoid having to allocate it (and free it) for each request, we pre-allocate it once and for all, at volume construction time; its access is (for the most part) not governed by *any* locks, because the block layer offers the core guarantee that only one FLUSH request can be pending at any given time, for each block device, therefore the state can never be accessed concurrently.  
-This state consists, among other things, of the memory area hosting the encrypted (and serialised) position map; this buffer is referenced by CWBs (Cacheline WriteBack requests), while no lock protects it: it is therefore necessary that no other code accesses it concurrently. This fundamental assumption of **non-reentrancy** is guaranteed, aside from the aforementioned property of the block layer, by the fact that the only other callers of the FLUSH functions are the volume constructor and destructor, which can never execute concurrently with I/O on the volume.
+This state consists, among other things, of the memory area hosting the encrypted (and serialised) position map; this buffer is referenced by the FLUSH's in-flight CWBs (Cacheline WriteBack requests), while no lock protects it: it is therefore necessary that no other code accesses it concurrently. This fundamental assumption of **non-reentrancy** is guaranteed, aside from the aforementioned property of the block layer, by the fact that the only other callers of the FLUSH function are the volume constructor and destructor, which can never execute concurrently with I/O on the volume.
+
+
+### Pseudocode
+
+The following picture illustrates the position map and its ancillary fields (including the FLUSH state), allocated once per volume.
+
+![Position Map fields](images/posmap.drawio.png)