1# SPDK "Reduce" Block Compression Algorithm {#reduce} 2 3## Overview 4 5The SPDK "reduce" block compression scheme is based on using SSDs for storing compressed blocks of 6storage and persistent memory for metadata. This metadata includes mappings of logical blocks 7requested by a user to the compressed blocks on SSD. The scheme described in this document 8is generic and not tied to any specific block device framework such as the SPDK block device (bdev) 9framework. This algorithm will be implemented in a library called "libreduce". Higher-level 10software modules can built on top of this library to create and present block devices in a 11specific block device framework. For SPDK, a bdev_reduce module will serve as a wrapper around 12the libreduce library, to present the compressed block devices as an SPDK bdev. 13 14This scheme only describes how compressed blocks are stored on an SSD and the metadata for tracking 15those compressed blocks. It relies on the higher-software module to perform the compression 16algorithm itself. For SPDK, the bdev_reduce module will utilize the DPDK compressdev framework 17to perform compression and decompression on behalf of the libreduce library. 18 19(Note that in some cases, blocks of storage may not be compressible, or cannot be compressed enough 20to realize savings from the compression. In these cases, the data may be stored uncompressed on 21disk. The phrase "compressed blocks of storage" includes these uncompressed blocks.) 22 23A compressed block device is a logical entity built on top of a similarly-sized backing storage 24device. The backing storage device must be thin-provisioned to realize any savings from 25compression for reasons described later in this document. This algorithm has no direct knowledge 26of the implementation of the backing storage device, except that it will always use the 27lowest-numbered blocks available on the backing storage device. This will ensure that when this 28algorithm is used on a thin-provisioned backing storage device, blocks will not be allocated until 29they are actually needed. 30 31The backing storage device must be sized for the worst case scenario, where no data can be 32compressed. In this case, the size of the backing storage device would be the same as the 33compressed block device. Since this algorithm ensures atomicity by never overwriting data 34in place, some additional backing storage is required to temporarily store data for writes in 35progress before the associated metadata is updated. 36 37Storage from the backing storage device will be allocated, read, and written to in 4KB units for 38best NVMe performance. These 4KB units are called "backing IO units". They are indexed from 0 to N-1 39with the indices called "backing IO unit indices". At start, the full set of indices represent the 40"free backing IO unit list". 41 42A compressed block device compresses and decompresses data in units of chunks, where a chunk is a 43multiple of at least two 4KB backing IO units. The number of backing IO units per chunk determines 44the chunk size and is specified when the compressed block device is created. A chunk 45consumes a number of 4KB backing IO units between 1 and the number of 4KB units in the chunk. For 46example, a 16KB chunk consumes 1, 2, 3 or 4 backing IO units. The number of backing IO units depends on how 47much the chunk was able to be compressed. The blocks on disk associated with a chunk are stored in a 48"chunk map" in persistent memory. Each chunk map consists of N 64-bit values, where N is the maximum 49number of backing IO units in the chunk. Each 64-bit value corresponds to a backing IO unit index. A 50special value (for example, 2^64-1) is used for backing IO units not needed due to compression. The 51number of chunk maps allocated is equal to the size of the compressed block device divided by its chunk 52size, plus some number of extra chunk maps. These extra chunk maps are used to ensure atomicity on 53writes and will be explained later in this document. At start, all of the chunk maps represent the 54"free chunk map list". 55 56Finally, the logical view of the compressed block device is represented by the "logical map". The 57logical map is a mapping of chunk offsets into the compressed block device to the corresponding 58chunk map. Each entry in the logical map is a 64-bit value, denoting the associated chunk map. 59A special value (UINT64_MAX) is used if there is no associated chunk map. The mapping is 60determined by dividing the byte offset by the chunk size to get an index, which is used as an 61array index into the array of chunk map entries. At start, all entries in the logical map have no 62associated chunk map. Note that while access to the backing storage device is in 4KB units, the 63logical view may allow 4KB or 512B unit access and should perform similarly. 64 65## Example 66 67To illustrate this algorithm, we will use a real example at a very small scale. 68 69The size of the compressed block device is 64KB, with a chunk size of 16KB. This will 70realize the following: 71 72* "Backing storage" will consist of an 80KB thin-provisioned logical volume. This 73 corresponds to the 64KB size of the compressed block device, plus an extra 16KB to handle 74 additional write operations under a worst-case compression scenario. 75* "Free backing IO unit list" will consist of indices 0 through 19 (inclusive). These represent 76 the 20 4KB IO units in the backing storage. 77* A "chunk map" will be 32 bytes in size. This corresponds to 4 backing IO units per chunk 78 (16KB / 4KB), and 8B (64b) per backing IO unit index. 79* 5 chunk maps will be allocated in 160B of persistent memory. This corresponds to 4 chunk maps 80 for the 4 chunks in the compressed block device (64KB / 16KB), plus an extra chunk map for use 81 when overwriting an existing chunk. 82* "Free chunk map list" will consist of indices 0 through 4 (inclusive). These represent the 83 5 allocated chunk maps. 84* The "logical map" will be allocated in 32B of persistent memory. This corresponds to 85 4 entries for the 4 chunks in the compressed block device and 8B (64b) per entry. 86 87In these examples, the value "X" will represent the special value (2^64-1) described above. 88 89### Initial Creation 90 91 +--------------------+ 92 Backing Device | | 93 +--------------------+ 94 95 Free Backing IO Unit List 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 96 97 +------------+------------+------------+------------+------------+ 98 Chunk Maps | | | | | | 99 +------------+------------+------------+------------+------------+ 100 101 Free Chunk Map List 0, 1, 2, 3, 4 102 103 +---+---+---+---+ 104 Logical Map | X | X | X | X | 105 +---+---+---+---+ 106 107### Write 16KB at Offset 32KB 108 109* Find the corresponding index into the logical map. Offset 32KB divided by the chunk size 110 (16KB) is 2. 111* Entry 2 in the logical map is "X". This means no part of this 16KB has been written to yet. 112* Allocate a 16KB buffer in memory 113* Compress the incoming 16KB of data into this allocated buffer 114* Assume this data compresses to 6KB. This requires 2 4KB backing IO units. 115* Allocate 2 blocks (0 and 1) from the free backing IO unit list. Always use the lowest numbered 116 entries in the free backing IO unit list - this ensures that unnecessary backing storage 117 is not allocated in the thin-provisioned logical volume holding the backing storage. 118* Write the 6KB of data to backing IO units 0 and 1. 119* Allocate a chunk map (0) from the free chunk map list. 120* Write (0, 1, X, X) to the chunk map. This represents that only 2 backing IO units were used to 121 store the 16KB of data. 122* Write the chunk map index to entry 2 in the logical map. 123 124 +--------------------+ 125 Backing Device |01 | 126 +--------------------+ 127 128 Free Backing IO Unit List 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 129 130 +------------+------------+------------+------------+------------+ 131 Chunk Maps | 0 1 X X | | | | | 132 +------------+------------+------------+------------+------------+ 133 134 Free Chunk Map List 1, 2, 3, 4 135 136 +---+---+---+---+ 137 Logical Map | X | X | 0 | X | 138 +---+---+---+---+ 139 140### Write 4KB at Offset 8KB 141 142* Find the corresponding index into the logical map. Offset 8KB divided by the chunk size is 0. 143* Entry 0 in the logical map is "X". This means no part of this 16KB has been written to yet. 144* The write is not for the entire 16KB chunk, so we must allocate a 16KB chunk-sized buffer for 145 source data. 146* Copy the incoming 4KB data to offset 8KB of this 16KB buffer. Zero the rest of the 16KB buffer. 147* Allocate a 16KB destination buffer. 148* Compress the 16KB source data buffer into the 16KB destination buffer 149* Assume this data compresses to 3KB. This requires 1 4KB backing IO unit. 150* Allocate 1 block (2) from the free backing IO unit list. 151* Write the 3KB of data to block 2. 152* Allocate a chunk map (1) from the free chunk map list. 153* Write (2, X, X, X) to the chunk map. 154* Write the chunk map index to entry 0 in the logical map. 155 156 +--------------------+ 157 Backing Device |012 | 158 +--------------------+ 159 160 Free Backing IO Unit List 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 161 162 +------------+------------+------------+------------+------------+ 163 Chunk Maps | 0 1 X X | 2 X X X | | | | 164 +------------+------------+------------+------------+------------+ 165 166 Free Chunk Map List 2, 3, 4 167 168 +---+---+---+---+ 169 Logical Map | 1 | X | 0 | X | 170 +---+---+---+---+ 171 172### Read 16KB at Offset 16KB 173 174* Offset 16KB maps to index 1 in the logical map. 175* Entry 1 in the logical map is "X". This means no part of this 16KB has been written to yet. 176* Since no data has been written to this chunk, return all 0's to satisfy the read I/O. 177 178### Write 4KB at Offset 4KB 179 180* Offset 4KB maps to index 0 in the logical map. 181* Entry 0 in the logical map is "1". Since we are not overwriting the entire chunk, we must 182 do a read-modify-write. 183* Chunk map 1 only specifies one backing IO unit (2). Allocate a 16KB buffer and read block 184 2 into it. This will be called the compressed data buffer. Note that 16KB is allocated 185 instead of 4KB so that we can reuse this buffer to hold the compressed data that will 186 be written later back to disk. 187* Allocate a 16KB buffer for the uncompressed data for this chunk. Decompress the data from 188 the compressed data buffer into this buffer. 189* Copy the incoming 4KB of data to offset 4KB of the uncompressed data buffer. 190* Compress the 16KB uncompressed data buffer into the compressed data buffer. 191* Assume this data compresses to 5KB. This requires 2 4KB backing IO units. 192* Allocate blocks 3 and 4 from the free backing IO unit list. 193* Write the 5KB of data to blocks 3 and 4. 194* Allocate chunk map 2 from the free chunk map list. 195* Write (3, 4, X, X) to chunk map 2. Note that at this point, the chunk map is not referenced 196 by the logical map. If there was a power fail at this point, the previous data for this chunk 197 would still be fully valid. 198* Write chunk map 2 to entry 0 in the logical map. 199* Free chunk map 1 back to the free chunk map list. 200* Free backing IO unit 2 back to the free backing IO unit list. 201 202 +--------------------+ 203 Backing Device |01 34 | 204 +--------------------+ 205 206 Free Backing IO Unit List 2, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 207 208 +------------+------------+------------+------------+------------+ 209 Chunk Maps | 0 1 X X | | 3 4 X X | | | 210 +------------+------------+------------+------------+------------+ 211 212 Free Chunk Map List 1, 3, 4 213 214 +---+---+---+---+ 215 Logical Map | 2 | X | 0 | X | 216 +---+---+---+---+ 217 218### Operations that span across multiple chunks 219 220Operations that span a chunk boundary are logically split into multiple operations, each of 221which is associated with a single chunk. 222 223Example: 20KB write at offset 4KB 224 225In this case, the write operation is split into a 12KB write at offset 4KB (affecting only 226chunk 0 in the logical map) and a 8KB write at offset 16KB (affecting only chunk 1 in the 227logical map). Each write is processed independently using the algorithm described above. 228Completion of the 20KB write does not occur until both operations have completed. 229 230### Unmap Operations 231 232Unmap operations on an entire chunk are achieved by removing the chunk map entry (if any) from 233the logical map. The chunk map is returned to the free chunk map list, and any backing IO units 234associated with the chunk map are returned to the free backing IO unit list. 235 236Unmap operations that affect only part of a chunk can be treated as writing zeroes to that 237region of the chunk. If the entire chunk is unmapped via several operations, it can be 238detected via the uncompressed data equaling all zeroes. When this occurs, the chunk map entry 239may be removed from the logical map. 240 241After an entire chunk has been unmapped, subsequent reads to the chunk will return all zeroes. 242This is similar to the "Read 16KB at offset 16KB" example above. 243 244### Write Zeroes Operations 245 246Write zeroes operations are handled similarly to unmap operations. If a write zeroes 247operation covers an entire chunk, we can remove the chunk's entry in the logical map 248completely. Then subsequent reads to that chunk will return all zeroes. 249 250### Restart 251 252An application using libreduce will periodically exit and need to be restarted. When the 253application restarts, it will reload compressed volumes so they can be used again from the 254same state as when the application exited. 255 256When the compressed volume is reloaded, the free chunk map list and free backing IO unit list 257are reconstructed by walking the logical map. The logical map will only point to valid 258chunk maps, and the valid chunk maps will only point to valid backing IO units. Any chunk maps 259and backing IO units not referenced go into their respective free lists. 260 261This ensures that if a system crashes in the middle of a write operation - i.e. during or 262after a chunk map is updated, but before it is written to the logical map - that everything 263related to that in-progress write will be ignored after the compressed volume is restarted. 264 265### Overlapping operations on same chunk 266 267Implementations must take care to handle overlapping operations on the same chunk. For example, 268operation 1 writes some data to chunk A, and while this is in progress, operation 2 also writes 269some data to chunk A. In this case, operation 2 should not start until operation 1 has 270completed. Further optimizations are outside the scope of this document. 271 272### Thin provisioned backing storage 273 274Backing storage must be thin provisioned to realize any savings from compression. This algorithm 275will always use (and reuse) backing IO units available closest to offset 0 on the backing device. 276This ensures that even though backing storage device may have been sized similarly to the size of 277the compressed volume, storage for the backing storage device will not actually be allocated 278until the backing IO units are actually needed. 279