bsd/vfs/vfs_journal.h

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