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