core/hfs_journal.h

   1 /*
   2  * Copyright (c) 2000-2015 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28 /*
  29  * This header contains the structures and function prototypes
  30  * for the vfs journaling code.  The data types are not meant
  31  * to be modified by user code.  Just use the functions and do
  32  * not mess around with the structs.
  33  */
  34 #ifndef HFS_JOURNAL_H_
  35 #define HFS_JOURNAL_H_
  36
  37 #include <sys/appleapiopts.h>
  38 #include <sys/cdefs.h>
  39
  40 #ifdef __APPLE_API_UNSTABLE
  41
  42 #include <sys/types.h>
  43 #include <kern/locks.h>
  44 #include <sys/disk.h>
  45
  46
  47 typedef struct _blk_info {
  48     int32_t    bsize;
  49     union {
  50         int32_t    cksum;
  51         uint32_t   sequence_num;
  52     } b;
  53 } _blk_info;
  54
  55 typedef struct block_info {
  56     off_t       bnum;                // block # on the file system device
  57     union {
  58         _blk_info   bi;
  59         struct buf *bp;
  60     } u;
  61 } __attribute__((__packed__)) block_info;
  62
  63 typedef struct block_list_header {
  64     u_int16_t   max_blocks;          // max number of blocks in this chunk
  65     u_int16_t   num_blocks;          // number of valid block numbers in block_nums
  66     int32_t     bytes_used;          // how many bytes of this tbuffer are used
  67     uint32_t     checksum;            // on-disk: checksum of this header and binfo[0]
  68     int32_t     flags;               // check-checksums, initial blhdr, etc
  69     block_info  binfo[1];            // so we can reference them by name
  70 } block_list_header;
  71
  72 #define BLHDR_CHECK_CHECKSUMS   0x0001
  73 #define BLHDR_FIRST_HEADER      0x0002
  74
  75
  76 struct journal;
  77
  78 struct jnl_trim_list {
  79         uint32_t        allocated_count;
  80         uint32_t        extent_count;
  81         dk_extent_t *extents;
  82 };
  83
  84 typedef void (*jnl_trim_callback_t)(void *arg, uint32_t extent_count, const dk_extent_t *extents);
  85
  86 typedef struct transaction {
  87     int                 tbuffer_size;  // in bytes
  88     char               *tbuffer;       // memory copy of the transaction
  89     block_list_header  *blhdr;         // points to the first byte of tbuffer
  90     int                 num_blhdrs;    // how many buffers we've allocated
  91     int                 total_bytes;   // total # of bytes in transaction
  92     int                 num_flushed;   // how many bytes have been flushed
  93     int                 num_killed;    // how many bytes were "killed"
  94     off_t               journal_start; // where in the journal this transaction starts
  95     off_t               journal_end;   // where in the journal this transaction ends
  96     struct journal     *jnl;           // ptr back to the journal structure
  97     struct transaction *next;          // list of tr's (either completed or to be free'd)
  98     uint32_t            sequence_num;
  99         struct jnl_trim_list trim;
 100     boolean_t           delayed_header_write;
 101         boolean_t       flush_on_completion; //flush transaction immediately upon txn end.
 102 } transaction;
 103
 104
 105 /*
 106  * This is written to block zero of the journal and it
 107  * maintains overall state about the journal.
 108  */
 109 typedef struct journal_header {
 110     int32_t        magic;
 111     int32_t        endian;
 112     volatile off_t start;         // zero-based byte offset of the start of the first transaction
 113     volatile off_t end;           // zero-based byte offset of where free space begins
 114     off_t          size;          // size in bytes of the entire journal
 115     int32_t        blhdr_size;    // size in bytes of each block_list_header in the journal
 116     uint32_t        checksum;
 117     int32_t        jhdr_size;     // block size (in bytes) of the journal header
 118     uint32_t       sequence_num;  // NEW FIELD: a monotonically increasing value assigned to all txn's
 119 } journal_header;
 120
 121 #define JOURNAL_HEADER_MAGIC  0x4a4e4c78   // 'JNLx'
 122 #define ENDIAN_MAGIC          0x12345678
 123
 124 //
 125 // we only checksum the original size of the journal_header to remain
 126 // backwards compatible.  the size of the original journal_heade is
 127 // everything up to the the sequence_num field, hence we use the
 128 // offsetof macro to calculate the size.
 129 //
 130 #define JOURNAL_HEADER_CKSUM_SIZE  (offsetof(struct journal_header, sequence_num))
 131
 132 #define OLD_JOURNAL_HEADER_MAGIC  0x4a484452   // 'JHDR'
 133
 134
 135 /*
 136  * In memory structure about the journal.
 137  */
 138 typedef struct journal {
 139     lck_mtx_t           jlock;             // protects the struct journal data
 140     lck_mtx_t           flock;             // serializes flushing of journal
 141         lck_rw_t            trim_lock;         // protects the async_trim field, below
 142
 143
 144     struct vnode       *jdev;              // vnode of the device where the journal lives
 145     off_t               jdev_offset;       // byte offset to the start of the journal
 146     const char         *jdev_name;
 147
 148     struct vnode       *fsdev;             // vnode of the file system device
 149     struct mount       *fsmount;           // mount of the file system
 150
 151     void              (*flush)(void *arg); // fs callback to flush meta data blocks
 152     void               *flush_arg;         // arg that's passed to flush()
 153
 154     int32_t             flags;
 155     int32_t             tbuffer_size;      // default transaction buffer size
 156     boolean_t           flush_aborted;
 157     boolean_t           flushing;
 158     boolean_t           asyncIO;
 159     boolean_t           writing_header;
 160     boolean_t           write_header_failed;
 161
 162     struct jnl_trim_list *async_trim;      // extents to be trimmed by transaction being asynchronously flushed
 163     jnl_trim_callback_t trim_callback;
 164     void                                *trim_callback_arg;
 165
 166     char               *header_buf;        // in-memory copy of the journal header
 167     int32_t             header_buf_size;
 168     journal_header     *jhdr;              // points to the first byte of header_buf
 169
 170         uint32_t                saved_sequence_num;
 171         uint32_t                sequence_num;
 172
 173     off_t               max_read_size;
 174     off_t               max_write_size;
 175
 176     transaction        *cur_tr;            // for group-commit
 177     transaction        *completed_trs;     // out-of-order transactions that completed
 178     transaction        *active_tr;         // for nested transactions
 179     int32_t             nested_count;      // for nested transactions
 180     void               *owner;             // a ptr that's unique to the calling process
 181
 182     transaction        *tr_freeme;         // transaction structs that need to be free'd
 183
 184     volatile off_t      active_start;      // the active start that we only keep in memory
 185     lck_mtx_t           old_start_lock;    // protects the old_start
 186     volatile off_t      old_start[16];     // this is how we do lazy start update
 187
 188     int                 last_flush_err;    // last error from flushing the cache
 189     uint32_t            flush_counter;     // a monotonically increasing value assigned on track cache flush
 190 } journal;
 191
 192 /* internal-only journal flags (top 16 bits) */
 193 #define JOURNAL_CLOSE_PENDING     0x00010000
 194 #define JOURNAL_INVALID           0x00020000
 195 #define JOURNAL_FLUSHCACHE_ERR    0x00040000   // means we already printed this err
 196 #define JOURNAL_NEED_SWAP         0x00080000   // swap any data read from disk
 197 #define JOURNAL_DO_FUA_WRITES     0x00100000   // do force-unit-access writes
 198 #define JOURNAL_USE_UNMAP         0x00200000   // device supports UNMAP (TRIM)
 199 #define JOURNAL_FEATURE_BARRIER   0x00400000   // device supports barrier-only flush
 200
 201
 202 /* journal_open/create options are always in the low-16 bits */
 203 #define JOURNAL_OPTION_FLAGS_MASK 0x0000ffff
 204
 205 __BEGIN_DECLS
 206 /*
 207  * Prototypes.
 208  */
 209
 210 /*
 211  * Call journal_init() to initialize the journaling code (sets up lock attributes)
 212  */
 213 void      journal_init(void);
 214
 215 /*
 216  * Call journal_create() to create a new journal.  You only
 217  * call this once, typically at file system creation time.
 218  *
 219  * The "jvp" argument is the vnode where the journal is written.
 220  * The journal starts at "offset" and is "journal_size" bytes long.
 221  *
 222  * The "fsvp" argument is the vnode of your file system.  It may be
 223  * the same as "jvp".
 224  *
 225  * The "min_fs_block_size" argument is the minimum block size
 226  * (in bytes) that the file system will ever write.  Typically
 227  * this is the block size of the file system (1k, 4k, etc) but
 228  * on HFS+ it is the minimum block size of the underlying device.
 229  *
 230  * The flags argument lets you disable group commit if you
 231  * want tighter guarantees on transactions (in exchange for
 232  * lower performance).
 233  *
 234  * The tbuffer_size is the size of the transaction buffer
 235  * used by the journal. If you specify zero, the journal code
 236  * will use a reasonable defaults.  The tbuffer_size should
 237  * be an integer multiple of the min_fs_block_size.
 238  *
 239  * Returns a valid journal pointer or NULL if one could not
 240  * be created.
 241  */
 242 journal *journal_create(struct vnode *jvp,
 243                                                 off_t         offset,
 244                                                 off_t         journal_size,
 245                                                 struct vnode *fsvp,
 246                                                 size_t        min_fs_block_size,
 247                                                 int32_t       flags,
 248                                                 int32_t       tbuffer_size,
 249                                                 void        (*flush)(void *arg),
 250                                                 void         *arg,
 251                                                 struct mount *fsmount);
 252
 253 /*
 254  * Call journal_open() when mounting an existing file system
 255  * that has a previously created journal.  It will take care
 256  * of validating the journal and replaying it if necessary.
 257  *
 258  * See journal_create() for a description of the arguments.
 259  *
 260  * Returns a valid journal pointer of NULL if it runs into
 261  * trouble reading/playing back the journal.
 262  */
 263 journal  *journal_open(struct vnode *jvp,
 264                                            off_t         offset,
 265                                            off_t         journal_size,
 266                                            struct vnode *fsvp,
 267                                            size_t        min_fs_block_size,
 268                                            int32_t       flags,
 269                                            int32_t       tbuffer_size,
 270                                            void        (*flush)(void *arg),
 271                                            void         *arg,
 272                                            struct mount *fsmount);
 273
 274 /*
 275  * Test whether the journal is clean or not.  This is intended
 276  * to be used when you're mounting read-only.  If the journal
 277  * is not clean for some reason then you should not mount the
 278  * volume as your data structures may be in an unknown state.
 279  */
 280 int journal_is_clean(struct vnode *jvp,
 281                      off_t         offset,
 282                      off_t         journal_size,
 283                      struct vnode *fsvp,
 284                      size_t        min_fs_block_size);
 285
 286
 287 /*
 288  * Call journal_close() just before your file system is unmounted.
 289  * It flushes any outstanding transactions and makes sure the
 290  * journal is in a consistent state.
 291  */
 292 void      journal_close(journal *journalp);
 293
 294 /*
 295  * flags for journal_create/open.  only can use
 296  * the low 16 bits for flags because internal
 297  * bits go in the high 16.
 298  */
 299 #define JOURNAL_NO_GROUP_COMMIT   0x00000001
 300 #define JOURNAL_RESET             0x00000002
 301
 302 /*
 303  * Transaction related functions.
 304  *
 305  * Before you start modifying file system meta data, you
 306  * should call journal_start_transaction().  Then before
 307  * you modify each block, call journal_modify_block_start()
 308  * and when you're done, journal_modify_block_end().  When
 309  * you've modified the last block as part of a transaction,
 310  * call journal_end_transaction() to commit the changes.
 311  *
 312  * If you decide to abort the modifications to a block you
 313  * should call journal_modify_block_abort().
 314  *
 315  * If as part of a transaction you need want to throw out
 316  * any previous copies of a block (because it got deleted)
 317  * then call journal_kill_block().  This will mark it so
 318  * that the journal does not play it back (effectively
 319  * dropping it).
 320  *
 321  * journal_trim_add_extent() marks a range of bytes on the device which should
 322  * be trimmed (invalidated, unmapped).  journal_trim_remove_extent() marks a
 323  * range of bytes which should no longer be trimmed.  Accumulated extents
 324  * will be trimmed when the transaction is flushed to the on-disk journal.
 325  */
 326 int   journal_start_transaction(journal *jnl);
 327 int   journal_modify_block_start(journal *jnl, struct buf *bp);
 328 int   journal_modify_block_abort(journal *jnl, struct buf *bp);
 329 int   journal_modify_block_end(journal *jnl, struct buf *bp, void (*func)(struct buf *bp, void *arg), void *arg);
 330 int   journal_kill_block(journal *jnl, struct buf *bp);
 331 int   journal_trim_add_extent(journal *jnl, uint64_t offset, uint64_t length);
 332 int   journal_trim_remove_extent(journal *jnl, uint64_t offset, uint64_t length);
 333 void  journal_trim_set_callback(journal *jnl, jnl_trim_callback_t callback, void *arg);
 334 int   journal_trim_extent_overlap (journal *jnl, uint64_t offset, uint64_t length, uint64_t *end);
 335 /* Mark state in the journal that requests an immediate journal flush upon txn completion */
 336 int   journal_request_immediate_flush (journal *jnl);
 337 int   journal_end_transaction(journal *jnl);
 338
 339 int   journal_active(journal *jnl);
 340
 341 typedef enum journal_flush_options {
 342         JOURNAL_WAIT_FOR_IO       = 0x01,   // Flush journal and metadata blocks, wait for async IO to complete.
 343         JOURNAL_FLUSH_FULL        = 0x02,   // Flush track cache to media
 344 } journal_flush_options_t;
 345
 346 int   journal_flush(journal *jnl, journal_flush_options_t options);
 347 void *journal_owner(journal *jnl);    // compare against current_thread()
 348 int   journal_uses_fua(journal *jnl);
 349 void  journal_lock(journal *jnl);
 350 void  journal_unlock(journal *jnl);
 351
 352
 353 /*
 354  * Relocate the journal.
 355  *
 356  * You provide the new starting offset and size for the journal. You may
 357  * optionally provide a new tbuffer_size; passing zero defaults to not
 358  * changing the tbuffer size except as needed to fit within the new journal
 359  * size.
 360  *
 361  * You must have already started a transaction. The transaction may contain
 362  * modified blocks (such as those needed to deallocate the old journal,
 363  * allocate the new journal, and update the location and size of the journal
 364  * in filesystem-private structures). Any transactions prior to the active
 365  * transaction will be flushed to the old journal. The new journal will be
 366  * initialized, and the blocks from the active transaction will be written to
 367  * the new journal. The caller will need to update the structures that
 368  * identify the location and size of the journal from the callback routine.
 369  */
 370 int journal_relocate(journal *jnl, off_t offset, off_t journal_size, int32_t tbuffer_size,
 371         errno_t (*callback)(void *), void *callback_arg);
 372
 373 uint32_t journal_current_txn(journal *jnl);
 374
 375 __END_DECLS
 376
 377 #endif /* __APPLE_API_UNSTABLE */
 378 #endif /* !HFS_JOURNAL_H_ */