bsd/vfs/vfs_journal.h

   1
   2 /*
   3  * Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved.
   4  *
   5  * @APPLE_LICENSE_HEADER_START@
   6  *
   7  * The contents of this file constitute Original Code as defined in and
   8  * are subject to the Apple Public Source License Version 1.1 (the
   9  * "License").  You may not use this file except in compliance with the
  10  * License.  Please obtain a copy of the License at
  11  * http://www.apple.com/publicsource and read it before using this file.
  12  *
  13  * This Original Code and all software distributed under the License are
  14  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  18  * License for the specific language governing rights and limitations
  19  * under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 /*
  24  * This header contains the structures and function prototypes
  25  * for the vfs journaling code.  The data types are not meant
  26  * to be modified by user code.  Just use the functions and do
  27  * not mess around with the structs.
  28  */
  29 #ifndef _SYS_VFS_JOURNAL_H_
  30 #define _SYS_VFS_JOURNAL_H_
  31
  32 #include <sys/appleapiopts.h>
  33
  34 #ifdef __APPLE_API_UNSTABLE
  35
  36 #include <sys/types.h>
  37 #include <sys/lock.h>
  38
  39 typedef struct block_info {
  40     off_t       bnum;                // block # on the file system device
  41     size_t      bsize;               // in bytes
  42     struct buf *bp;
  43 } block_info;
  44
  45 typedef struct block_list_header {
  46     u_int16_t   max_blocks;          // max number of blocks in this chunk
  47     u_int16_t   num_blocks;          // number of valid block numbers in block_nums
  48     int32_t     bytes_used;          // how many bytes of this tbuffer are used
  49     int32_t     checksum;            // on-disk: checksum of this header and binfo[0]
  50     int32_t     pad;                 // pad out to 16 bytes
  51     block_info  binfo[1];            // so we can reference them by name
  52 } block_list_header;
  53
  54
  55 struct journal;
  56
  57 typedef struct transaction {
  58     int                 tbuffer_size;  // in bytes
  59     char               *tbuffer;       // memory copy of the transaction
  60     block_list_header  *blhdr;         // points to the first byte of tbuffer
  61     int                 num_blhdrs;    // how many buffers we've allocated
  62     int                 total_bytes;   // total # of bytes in transaction
  63     int                 num_flushed;   // how many bytes have been flushed
  64     int                 num_killed;    // how many bytes were "killed"
  65     off_t               journal_start; // where in the journal this transaction starts
  66     off_t               journal_end;   // where in the journal this transaction ends
  67     struct journal     *jnl;           // ptr back to the journal structure
  68     struct transaction *next;          // list of tr's (either completed or to be free'd)
  69 } transaction;
  70
  71
  72 /*
  73  * This is written to block zero of the journal and it
  74  * maintains overall state about the journal.
  75  */
  76 typedef struct journal_header {
  77     int32_t        magic;
  78     int32_t        endian;
  79     volatile off_t start;         // zero-based byte offset of the start of the first transaction
  80     volatile off_t end;           // zero-based byte offset of where free space begins
  81     off_t          size;          // size in bytes of the entire journal
  82     int32_t        blhdr_size;    // size in bytes of each block_list_header in the journal
  83     int32_t        checksum;
  84     int32_t        jhdr_size;     // block size (in bytes) of the journal header
  85 } journal_header;
  86
  87 #define JOURNAL_HEADER_MAGIC  0x4a4e4c78   // 'JNLx'
  88 #define ENDIAN_MAGIC          0x12345678
  89
  90 #define OLD_JOURNAL_HEADER_MAGIC  0x4a484452   // 'JHDR'
  91
  92
  93 /*
  94  * In memory structure about the journal.
  95  */
  96 typedef struct journal {
  97         struct lock__bsd__      jlock;
  98
  99     struct vnode       *jdev;              // vnode of the device where the journal lives
 100     off_t               jdev_offset;       // byte offset to the start of the journal
 101
 102     struct vnode       *fsdev;             // vnode of the file system device
 103
 104     void              (*flush)(void *arg); // fs callback to flush meta data blocks
 105     void               *flush_arg;         // arg that's passed to flush()
 106
 107     int32_t             flags;
 108     int32_t             tbuffer_size;      // default transaction buffer size
 109
 110     char               *header_buf;        // in-memory copy of the journal header
 111     journal_header     *jhdr;              // points to the first byte of header_buf
 112
 113     transaction        *cur_tr;            // for group-commit
 114     transaction        *completed_trs;     // out-of-order transactions that completed
 115     transaction        *active_tr;         // for nested transactions
 116     int32_t             nested_count;      // for nested transactions
 117     void               *owner;             // a ptr that's unique to the calling process
 118
 119     transaction        *tr_freeme;         // transaction structs that need to be free'd
 120
 121         volatile off_t      active_start;      // the active start that we only keep in memory
 122         simple_lock_data_t  old_start_lock;    // guard access
 123         volatile off_t      old_start[16];     // this is how we do lazy start update
 124
 125         int                 last_flush_err;    // last error from flushing the cache
 126 } journal;
 127
 128 /* internal-only journal flags (top 16 bits) */
 129 #define JOURNAL_CLOSE_PENDING     0x00010000
 130 #define JOURNAL_INVALID           0x00020000
 131 #define JOURNAL_FLUSHCACHE_ERR    0x00040000   // means we already printed this err
 132 #define JOURNAL_NEED_SWAP         0x00080000   // swap any data read from disk
 133
 134 /* journal_open/create options are always in the low-16 bits */
 135 #define JOURNAL_OPTION_FLAGS_MASK 0x0000ffff
 136
 137 /*
 138  * Prototypes.
 139  */
 140
 141 /*
 142  * Call journal_create() to create a new journal.  You only
 143  * call this once, typically at file system creation time.
 144  *
 145  * The "jvp" argument is the vnode where the journal is written.
 146  * The journal starts at "offset" and is "journal_size" bytes long.
 147  *
 148  * The "fsvp" argument is the vnode of your file system.  It may be
 149  * the same as "jvp".
 150  *
 151  * The "min_fs_block_size" argument is the minimum block size
 152  * (in bytes) that the file system will ever write.  Typically
 153  * this is the block size of the file system (1k, 4k, etc) but
 154  * on HFS+ it is the minimum block size of the underlying device.
 155  *
 156  * The flags argument lets you disable group commit if you
 157  * want tighter guarantees on transactions (in exchange for
 158  * lower performance).
 159  *
 160  * The tbuffer_size is the size of the transaction buffer
 161  * used by the journal. If you specify zero, the journal code
 162  * will use a reasonable defaults.  The tbuffer_size should
 163  * be an integer multiple of the min_fs_block_size.
 164  *
 165  * Returns a valid journal pointer or NULL if one could not
 166  * be created.
 167  */
 168 journal *journal_create(struct vnode *jvp,
 169                                                 off_t         offset,
 170                                                 off_t         journal_size,
 171                                                 struct vnode *fsvp,
 172                                                 size_t        min_fs_block_size,
 173                                                 int32_t       flags,
 174                                                 int32_t       tbuffer_size,
 175                                                 void        (*flush)(void *arg),
 176                                                 void         *arg);
 177
 178 /*
 179  * Call journal_open() when mounting an existing file system
 180  * that has a previously created journal.  It will take care
 181  * of validating the journal and replaying it if necessary.
 182  *
 183  * See journal_create() for a description of the arguments.
 184  *
 185  * Returns a valid journal pointer of NULL if it runs into
 186  * trouble reading/playing back the journal.
 187  */
 188 journal  *journal_open(struct vnode *jvp,
 189                                            off_t         offset,
 190                                            off_t         journal_size,
 191                                            struct vnode *fsvp,
 192                                            size_t        min_fs_block_size,
 193                                            int32_t       flags,
 194                                            int32_t       tbuffer_size,
 195                                            void        (*flush)(void *arg),
 196                                            void         *arg);
 197
 198 /*
 199  * Call journal_close() just before your file system is unmounted.
 200  * It flushes any outstanding transactions and makes sure the
 201  * journal is in a consistent state.
 202  */
 203 void      journal_close(journal *journal);
 204
 205 /*
 206  * flags for journal_create/open.  only can use
 207  * the low 16 bits for flags because internal
 208  * bits go in the high 16.
 209  */
 210 #define JOURNAL_NO_GROUP_COMMIT   0x00000001
 211 #define JOURNAL_RESET             0x00000002
 212
 213 /*
 214  * Transaction related functions.
 215  *
 216  * Before you start modifying file system meta data, you
 217  * should call journal_start_transaction().  Then before
 218  * you modify each block, call journal_modify_block_start()
 219  * and when you're done, journal_modify_block_end().  When
 220  * you've modified the last block as part of a transaction,
 221  * call journal_end_transaction() to commit the changes.
 222  *
 223  * If you decide to abort the modifications to a block you
 224  * should call journal_modify_block_abort().
 225  *
 226  * If as part of a transaction you need want to throw out
 227  * any previous copies of a block (because it got deleted)
 228  * then call journal_kill_block().  This will mark it so
 229  * that the journal does not play it back (effectively
 230  * dropping it).
 231  */
 232 int   journal_start_transaction(journal *jnl);
 233 int   journal_modify_block_start(journal *jnl, struct buf *bp);
 234 int   journal_modify_block_abort(journal *jnl, struct buf *bp);
 235 int   journal_modify_block_end(journal *jnl, struct buf *bp);
 236 int   journal_kill_block(journal *jnl, struct buf *bp);
 237 int   journal_end_transaction(journal *jnl);
 238
 239 int   journal_active(journal *jnl);
 240 int   journal_flush(journal *jnl);
 241
 242 #endif /* __APPLE_API_UNSTABLE */
 243 #endif /* !_SYS_VFS_JOURNAL_H_ */