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 46typedef 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 56typedef 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 69struct journal; 70 71typedef 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 */ 91typedef 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 */ 120typedef 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 */ 174void 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 */ 203journal *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 */ 223journal *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 */ 239int 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 */ 251void 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 */ 280int journal_start_transaction(journal *jnl); 281int journal_modify_block_start(journal *jnl, struct buf *bp); 282int journal_modify_block_abort(journal *jnl, struct buf *bp); 283int journal_modify_block_end(journal *jnl, struct buf *bp, void (*func)(struct buf *bp, void *arg), void *arg); 284int journal_kill_block(journal *jnl, struct buf *bp); 285int journal_end_transaction(journal *jnl); 286 287int journal_active(journal *jnl); 288int journal_flush(journal *jnl); 289void *journal_owner(journal *jnl); // compare against current_thread() 290int 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 */ 310int 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_ */ 317