From 7eb09b8b00c30cedbcbd4bccceb74793c46bcd4a Mon Sep 17 00:00:00 2001 From: toninov Date: Sun, 5 Oct 2025 15:14:36 +0200 Subject: [PATCH] Add image --- docs/images/posmap.drawio.png | Bin 0 -> 22937 bytes docs/locking.md | 9 ++++++++- 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 docs/images/posmap.drawio.png diff --git a/docs/images/posmap.drawio.png b/docs/images/posmap.drawio.png new file mode 100644 index 0000000000000000000000000000000000000000..0da2a7b940d1d075480d5ad101a8316bb43e81f7 GIT binary patch literal 22937 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 VE}x(2-UUJu!uJmH+U*gZ^M8E1Q}6%) literal 0 HcmV?d00001 diff --git a/docs/locking.md b/docs/locking.md index 9f2c6db..1d5e8d3 100644 --- a/docs/locking.md +++ b/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)