1 // SPDX-License-Identifier: CDDL-1.0 2 /* 3 * CDDL HEADER START 4 * 5 * The contents of this file are subject to the terms of the 6 * Common Development and Distribution License (the "License"). 7 * You may not use this file except in compliance with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or https://opensource.org/licenses/CDDL-1.0. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright 2009 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 /* 28 * Copyright (c) 2012, 2015 by Delphix. All rights reserved. 29 * Copyright (c) 2024, Klara Inc. 30 */ 31 32 #ifndef _ZIO_IMPL_H 33 #define _ZIO_IMPL_H 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 /* 40 * XXX -- Describe ZFS I/O pipeline here. Fill in as needed. 41 * 42 * The ZFS I/O pipeline is comprised of various stages which are defined 43 * in the zio_stage enum below. The individual stages are used to construct 44 * these basic I/O operations: Read, Write, Free, Claim, Flush and Trim. 45 * 46 * I/O operations: (XXX - provide detail for each of the operations) 47 * 48 * Read: 49 * Write: 50 * Free: 51 * Claim: 52 * Flush: 53 * Trim: 54 * 55 * Although the most common pipeline are used by the basic I/O operations 56 * above, there are some helper pipelines (one could consider them 57 * sub-pipelines) which are used internally by the ZIO module and are 58 * explained below: 59 * 60 * Interlock Pipeline: 61 * The interlock pipeline is the most basic pipeline and is used by all 62 * of the I/O operations. The interlock pipeline does not perform any I/O 63 * and is used to coordinate the dependencies between I/Os that are being 64 * issued (i.e. the parent/child relationship). 65 * 66 * Vdev child Pipeline: 67 * The vdev child pipeline is responsible for performing the physical I/O. 68 * It is in this pipeline where the I/O are queued and possibly cached. 69 * 70 * In addition to performing I/O, the pipeline is also responsible for 71 * data transformations. The transformations performed are based on the 72 * specific properties that user may have selected and modify the 73 * behavior of the pipeline. Examples of supported transformations are 74 * compression, dedup, and nop writes. Transformations will either modify 75 * the data or the pipeline. This list below further describes each of 76 * the supported transformations: 77 * 78 * Compression: 79 * ZFS supports five different flavors of compression -- gzip, lzjb, lz4, zle, 80 * and zstd. Compression occurs as part of the write pipeline and is 81 * performed in the ZIO_STAGE_WRITE_BP_INIT stage. 82 * 83 * Block cloning: 84 * The block cloning functionality introduces ZIO_STAGE_BRT_FREE stage which 85 * is called during a free pipeline. If the block is referenced in the 86 * Block Cloning Table (BRT) we will just decrease its reference counter 87 * instead of actually freeing the block. 88 * 89 * Dedup: 90 * Dedup reads are handled by the ZIO_STAGE_DDT_READ_START and 91 * ZIO_STAGE_DDT_READ_DONE stages. These stages are added to an existing 92 * read pipeline if the dedup bit is set on the block pointer. 93 * Writing a dedup block is performed by the ZIO_STAGE_DDT_WRITE stage 94 * and added to a write pipeline if a user has enabled dedup on that 95 * particular dataset. 96 * 97 * NOP Write: 98 * The NOP write feature is performed by the ZIO_STAGE_NOP_WRITE stage 99 * and is added to an existing write pipeline if a cryptographically 100 * secure checksum (i.e. SHA256) is enabled and compression is turned on. 101 * The NOP write stage will compare the checksums of the current data 102 * on-disk (level-0 blocks only) and the data that is currently being written. 103 * If the checksum values are identical then the pipeline is converted to 104 * an interlock pipeline skipping block allocation and bypassing the 105 * physical I/O. The nop write feature can handle writes in either 106 * syncing or open context (i.e. zil writes) and as a result is mutually 107 * exclusive with dedup. 108 * 109 * Encryption: 110 * Encryption and authentication is handled by the ZIO_STAGE_ENCRYPT stage. 111 * This stage determines how the encryption metadata is stored in the bp. 112 * Decryption and MAC verification is performed during zio_decrypt() as a 113 * transform callback. Encryption is mutually exclusive with nopwrite, because 114 * blocks with the same plaintext will be encrypted with different salts and 115 * IV's (if dedup is off), and therefore have different ciphertexts. For dedup 116 * blocks we deterministically generate the IV and salt by performing an HMAC 117 * of the plaintext, which is computationally expensive, but allows us to keep 118 * support for encrypted dedup. See the block comment in zio_crypt.c for 119 * details. 120 */ 121 122 /* 123 * zio pipeline stage definitions 124 * 125 * NOTE: PLEASE UPDATE THE BITFIELD STRINGS IN zfs_valstr.c IF YOU ADD ANOTHER 126 * FLAG. 127 */ 128 enum zio_stage { 129 ZIO_STAGE_OPEN = 1 << 0, /* RWFCXT */ 130 131 ZIO_STAGE_READ_BP_INIT = 1 << 1, /* R----- */ 132 ZIO_STAGE_WRITE_BP_INIT = 1 << 2, /* -W---- */ 133 ZIO_STAGE_FREE_BP_INIT = 1 << 3, /* --F--- */ 134 ZIO_STAGE_ISSUE_ASYNC = 1 << 4, /* -WF--T */ 135 ZIO_STAGE_WRITE_COMPRESS = 1 << 5, /* -W---- */ 136 137 ZIO_STAGE_ENCRYPT = 1 << 6, /* -W---- */ 138 ZIO_STAGE_CHECKSUM_GENERATE = 1 << 7, /* -W---- */ 139 140 ZIO_STAGE_NOP_WRITE = 1 << 8, /* -W---- */ 141 142 ZIO_STAGE_BRT_FREE = 1 << 9, /* --F--- */ 143 144 ZIO_STAGE_DDT_READ_START = 1 << 10, /* R----- */ 145 ZIO_STAGE_DDT_READ_DONE = 1 << 11, /* R----- */ 146 ZIO_STAGE_DDT_WRITE = 1 << 12, /* -W---- */ 147 ZIO_STAGE_DDT_FREE = 1 << 13, /* --F--- */ 148 149 ZIO_STAGE_GANG_ASSEMBLE = 1 << 14, /* RWFC-- */ 150 ZIO_STAGE_GANG_ISSUE = 1 << 15, /* RWFC-- */ 151 152 ZIO_STAGE_DVA_THROTTLE = 1 << 16, /* -W---- */ 153 ZIO_STAGE_DVA_ALLOCATE = 1 << 17, /* -W---- */ 154 ZIO_STAGE_DVA_FREE = 1 << 18, /* --F--- */ 155 ZIO_STAGE_DVA_CLAIM = 1 << 19, /* ---C-- */ 156 157 ZIO_STAGE_READY = 1 << 20, /* RWFCXT */ 158 159 ZIO_STAGE_VDEV_IO_START = 1 << 21, /* RW--XT */ 160 ZIO_STAGE_VDEV_IO_DONE = 1 << 22, /* RW--XT */ 161 ZIO_STAGE_VDEV_IO_ASSESS = 1 << 23, /* RW--XT */ 162 163 ZIO_STAGE_CHECKSUM_VERIFY = 1 << 24, /* R----- */ 164 ZIO_STAGE_DIO_CHECKSUM_VERIFY = 1 << 25, /* -W---- */ 165 166 ZIO_STAGE_DONE = 1 << 26 /* RWFCXT */ 167 }; 168 169 #define ZIO_ROOT_PIPELINE \ 170 ZIO_STAGE_DONE 171 172 #define ZIO_INTERLOCK_STAGES \ 173 (ZIO_STAGE_READY | \ 174 ZIO_STAGE_DONE) 175 176 #define ZIO_INTERLOCK_PIPELINE \ 177 ZIO_INTERLOCK_STAGES 178 179 #define ZIO_VDEV_IO_STAGES \ 180 (ZIO_STAGE_VDEV_IO_START | \ 181 ZIO_STAGE_VDEV_IO_DONE | \ 182 ZIO_STAGE_VDEV_IO_ASSESS) 183 184 #define ZIO_VDEV_CHILD_PIPELINE \ 185 (ZIO_VDEV_IO_STAGES | \ 186 ZIO_STAGE_DONE) 187 188 #define ZIO_READ_COMMON_STAGES \ 189 (ZIO_INTERLOCK_STAGES | \ 190 ZIO_VDEV_IO_STAGES | \ 191 ZIO_STAGE_CHECKSUM_VERIFY) 192 193 #define ZIO_READ_PHYS_PIPELINE \ 194 ZIO_READ_COMMON_STAGES 195 196 #define ZIO_READ_PIPELINE \ 197 (ZIO_READ_COMMON_STAGES | \ 198 ZIO_STAGE_READ_BP_INIT) 199 200 #define ZIO_DDT_CHILD_READ_PIPELINE \ 201 ZIO_READ_COMMON_STAGES 202 203 #define ZIO_DDT_READ_PIPELINE \ 204 (ZIO_INTERLOCK_STAGES | \ 205 ZIO_STAGE_READ_BP_INIT | \ 206 ZIO_STAGE_DDT_READ_START | \ 207 ZIO_STAGE_DDT_READ_DONE) 208 209 #define ZIO_WRITE_COMMON_STAGES \ 210 (ZIO_INTERLOCK_STAGES | \ 211 ZIO_VDEV_IO_STAGES | \ 212 ZIO_STAGE_ISSUE_ASYNC | \ 213 ZIO_STAGE_CHECKSUM_GENERATE) 214 215 #define ZIO_WRITE_PHYS_PIPELINE \ 216 ZIO_WRITE_COMMON_STAGES 217 218 #define ZIO_REWRITE_PIPELINE \ 219 (ZIO_WRITE_COMMON_STAGES | \ 220 ZIO_STAGE_WRITE_COMPRESS | \ 221 ZIO_STAGE_ENCRYPT | \ 222 ZIO_STAGE_WRITE_BP_INIT) 223 224 #define ZIO_WRITE_PIPELINE \ 225 (ZIO_WRITE_COMMON_STAGES | \ 226 ZIO_STAGE_WRITE_BP_INIT | \ 227 ZIO_STAGE_WRITE_COMPRESS | \ 228 ZIO_STAGE_ENCRYPT | \ 229 ZIO_STAGE_DVA_THROTTLE | \ 230 ZIO_STAGE_DVA_ALLOCATE) 231 232 #define ZIO_DIRECT_WRITE_PIPELINE \ 233 ZIO_WRITE_PIPELINE & \ 234 (~ZIO_STAGE_ISSUE_ASYNC) 235 236 #define ZIO_DDT_CHILD_WRITE_PIPELINE \ 237 (ZIO_INTERLOCK_STAGES | \ 238 ZIO_VDEV_IO_STAGES | \ 239 ZIO_STAGE_DVA_THROTTLE | \ 240 ZIO_STAGE_DVA_ALLOCATE) 241 242 #define ZIO_DDT_WRITE_PIPELINE \ 243 (ZIO_INTERLOCK_STAGES | \ 244 ZIO_STAGE_WRITE_BP_INIT | \ 245 ZIO_STAGE_ISSUE_ASYNC | \ 246 ZIO_STAGE_WRITE_COMPRESS | \ 247 ZIO_STAGE_ENCRYPT | \ 248 ZIO_STAGE_CHECKSUM_GENERATE | \ 249 ZIO_STAGE_DDT_WRITE) 250 251 #define ZIO_GANG_STAGES \ 252 (ZIO_STAGE_GANG_ASSEMBLE | \ 253 ZIO_STAGE_GANG_ISSUE) 254 255 #define ZIO_FREE_PIPELINE \ 256 (ZIO_INTERLOCK_STAGES | \ 257 ZIO_STAGE_FREE_BP_INIT | \ 258 ZIO_STAGE_BRT_FREE | \ 259 ZIO_STAGE_DVA_FREE) 260 261 #define ZIO_DDT_FREE_PIPELINE \ 262 (ZIO_INTERLOCK_STAGES | \ 263 ZIO_STAGE_FREE_BP_INIT | \ 264 ZIO_STAGE_ISSUE_ASYNC | \ 265 ZIO_STAGE_DDT_FREE) 266 267 #define ZIO_CLAIM_PIPELINE \ 268 (ZIO_INTERLOCK_STAGES | \ 269 ZIO_STAGE_DVA_CLAIM) 270 271 #define ZIO_FLUSH_PIPELINE \ 272 (ZIO_INTERLOCK_STAGES | \ 273 ZIO_VDEV_IO_STAGES) 274 275 #define ZIO_TRIM_PIPELINE \ 276 (ZIO_INTERLOCK_STAGES | \ 277 ZIO_STAGE_ISSUE_ASYNC | \ 278 ZIO_VDEV_IO_STAGES) 279 280 #define ZIO_BLOCKING_STAGES \ 281 (ZIO_STAGE_DVA_ALLOCATE | \ 282 ZIO_STAGE_DVA_CLAIM | \ 283 ZIO_STAGE_VDEV_IO_START) 284 285 extern void zio_inject_init(void); 286 extern void zio_inject_fini(void); 287 288 #ifdef __cplusplus 289 } 290 #endif 291 292 #endif /* _ZIO_IMPL_H */ 293