diff options
| -rw-r--r-- | share/man/man9/dcdr.9 | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/share/man/man9/dcdr.9 b/share/man/man9/dcdr.9 new file mode 100644 index 0000000..1b8995a --- /dev/null +++ b/share/man/man9/dcdr.9 @@ -0,0 +1,127 @@ +.\" Copyright (c) 2023-2024 Ian Marco Moffett and the Osmora Team. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of Hyra nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.Dd Dec 16 2024 +.Dt DCDR 9 +.Os Hyra +.Sh NAME +.Nm dcdr - drive cache descriptor ring +.Sh SYNOPSIS +.In dev/dcdr/cache.h + +.Ft struct dcdr * +.Fn dcdr_alloc "size_t bsize" "size_t cap" +.Ft struct dcd * +.Fn dcdr_cachein "struct dcdr *dcdr" "void *block" "off_t lba" + +.Ft struct dcd * +.Fn dcdr_lbc_cachein "struct dcdr *dcdr" "void *block" "off_t lba" +.Ft int +.Fn dcdr_lookup "struct dcdr *dcdr" "off_t lba" "struct dcdr_lookup *res" +.Ft int +.Fn dcdr_invldcd "struct dcdr *dcdr" "off_t lba" + +.Sh DESCRIPTION +The Drive Cache Descriptor Ring (DCDR) framework is used for +caching of read/write operations for LBA-based storage media +(e.g., certain SSDs and HDDs). + +The +.Ft dcd +(drive cache descriptor) structure describes +a single logical block within some storage media. + +The +.Ft dcdr +structure describes a drive cache descriptor ring (DCDR). When a +logical block is cached, a drive cache descriptor (DCD) +is created and added to the DCDR. + +The +.Ft dcdr_alloc +function allocates and returns a new DCDR. The size +of each logical block is denoted by +.Fa bsize . +And the maximum capacity of the DCDR is denoted by +.Fa cap . + +The +.Ft dcdr_cachein +function caches a logical block into a DCDR pointed to by +.Fa dcdr . +The +.Fa block +argument points to a buffer holding the data contained within +some logical block. It is recommended for this pointer to be aligned +by the storage device's block size. +The +.Fa lba +argument is the Logical Block Address (LBA) this data exists at +within the storage device. + +DCDR implements a concept called Logical Block Coalescing (LBC) +which is a method to optimize caching by combining a pair +of adjacent logical blocks into a single DCD. In other words, +two consecutive logical blocks can be represented +by a single DCD. To cache a block with LBC, the +.Ft dcdr_lbc_cachein +function can be used. + +The +.Fa dcdr +argument points to the target DCDR. + +The +.Fa block +argument points to the first logical block. This creates +a DCD that describes the first and next logical block. + +The +.Fa lba +argument is the LBA this data exists at within the storage +device. + +The +.Ft dcdr_lbc_cacheinp +function searches the DCDR for a logical block +at the LBA denoted by +.Fa lba . +The result is returned in a structure +pointed to by +.Fa res . + +The +.Ft dcdr_invldcd +function invalidates a single DCD from a +DCDR pointed to by +.Fa dcdr . +The +.Fa lba +argument denotes the Logical Block Address to +be searched for. + +.Sh AUTHORS +.An Ian Moffett Aq Mt ian@osmora.org |