include/sys/zio_impl.h

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