1 2/* 3 * Copyright (c) 2000-2011 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#include <sys/disk.h> 46 47 48typedef struct _blk_info { 49 int32_t bsize; 50 union { 51 int32_t cksum; 52 uint32_t sequence_num; 53 } b; 54} _blk_info; 55 56typedef struct block_info { 57 off_t bnum; // block # on the file system device 58 union { 59 _blk_info bi; 60 struct buf *bp; 61 } u; 62} __attribute__((__packed__)) block_info; 63 64typedef struct block_list_header { 65 u_int16_t max_blocks; // max number of blocks in this chunk 66 u_int16_t num_blocks; // number of valid block numbers in block_nums 67 int32_t bytes_used; // how many bytes of this tbuffer are used 68 uint32_t checksum; // on-disk: checksum of this header and binfo[0] 69 int32_t flags; // check-checksums, initial blhdr, etc 70 block_info binfo[1]; // so we can reference them by name 71} block_list_header; 72 73#define BLHDR_CHECK_CHECKSUMS 0x0001 74#define BLHDR_FIRST_HEADER 0x0002 75 76 77struct journal; 78 79struct jnl_trim_list { 80 uint32_t allocated_count; 81 uint32_t extent_count; 82 dk_extent_t *extents; 83}; 84 85typedef void (*jnl_trim_callback_t)(void *arg, uint32_t extent_count, const dk_extent_t *extents); 86 87typedef struct transaction { 88 int tbuffer_size; // in bytes 89 char *tbuffer; // memory copy of the transaction 90 block_list_header *blhdr; // points to the first byte of tbuffer 91 int num_blhdrs; // how many buffers we've allocated 92 int total_bytes; // total # of bytes in transaction 93 int num_flushed; // how many bytes have been flushed 94 int num_killed; // how many bytes were "killed" 95 off_t journal_start; // where in the journal this transaction starts 96 off_t journal_end; // where in the journal this transaction ends 97 struct journal *jnl; // ptr back to the journal structure 98 struct transaction *next; // list of tr's (either completed or to be free'd) 99 uint32_t sequence_num; 100 struct jnl_trim_list trim; 101 boolean_t delayed_header_write; 102 boolean_t flush_on_completion; //flush transaction immediately upon txn end. 103} transaction; 104 105 106/* 107 * This is written to block zero of the journal and it 108 * maintains overall state about the journal. 109 */ 110typedef struct journal_header { 111 int32_t magic; 112 int32_t endian; 113 volatile off_t start; // zero-based byte offset of the start of the first transaction 114 volatile off_t end; // zero-based byte offset of where free space begins 115 off_t size; // size in bytes of the entire journal 116 int32_t blhdr_size; // size in bytes of each block_list_header in the journal 117 uint32_t checksum; 118 int32_t jhdr_size; // block size (in bytes) of the journal header 119 uint32_t sequence_num; // NEW FIELD: a monotonically increasing value assigned to all txn's 120} journal_header; 121 122#define JOURNAL_HEADER_MAGIC 0x4a4e4c78 // 'JNLx' 123#define ENDIAN_MAGIC 0x12345678 124 125// 126// we only checksum the original size of the journal_header to remain 127// backwards compatible. the size of the original journal_heade is 128// everything up to the the sequence_num field, hence we use the 129// offsetof macro to calculate the size. 130// 131#define JOURNAL_HEADER_CKSUM_SIZE (offsetof(struct journal_header, sequence_num)) 132 133#define OLD_JOURNAL_HEADER_MAGIC 0x4a484452 // 'JHDR' 134 135 136/* 137 * In memory structure about the journal. 138 */ 139typedef struct journal { 140 lck_mtx_t jlock; // protects the struct journal data 141 lck_mtx_t flock; // serializes flushing of journal 142 lck_rw_t trim_lock; // protects the async_trim field, below 143 144 145 struct vnode *jdev; // vnode of the device where the journal lives 146 off_t jdev_offset; // byte offset to the start of the journal 147 const char *jdev_name; 148 149 struct vnode *fsdev; // vnode of the file system device 150 struct mount *fsmount; // mount of the file system 151 152 void (*flush)(void *arg); // fs callback to flush meta data blocks 153 void *flush_arg; // arg that's passed to flush() 154 155 int32_t flags; 156 int32_t tbuffer_size; // default transaction buffer size 157 boolean_t flush_aborted; 158 boolean_t flushing; 159 boolean_t asyncIO; 160 boolean_t writing_header; 161 boolean_t write_header_failed; 162 163 struct jnl_trim_list *async_trim; // extents to be trimmed by transaction being asynchronously flushed 164 jnl_trim_callback_t trim_callback; 165 void *trim_callback_arg; 166 167 char *header_buf; // in-memory copy of the journal header 168 int32_t header_buf_size; 169 journal_header *jhdr; // points to the first byte of header_buf 170 171 uint32_t saved_sequence_num; 172 uint32_t sequence_num; 173 174 off_t max_read_size; 175 off_t max_write_size; 176 177 transaction *cur_tr; // for group-commit 178 transaction *completed_trs; // out-of-order transactions that completed 179 transaction *active_tr; // for nested transactions 180 int32_t nested_count; // for nested transactions 181 void *owner; // a ptr that's unique to the calling process 182 183 transaction *tr_freeme; // transaction structs that need to be free'd 184 185 volatile off_t active_start; // the active start that we only keep in memory 186 lck_mtx_t old_start_lock; // protects the old_start 187 volatile off_t old_start[16]; // this is how we do lazy start update 188 189 int last_flush_err; // last error from flushing the cache 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 200 201/* journal_open/create options are always in the low-16 bits */ 202#define JOURNAL_OPTION_FLAGS_MASK 0x0000ffff 203 204__BEGIN_DECLS 205/* 206 * Prototypes. 207 */ 208 209/* 210 * Call journal_init() to initialize the journaling code (sets up lock attributes) 211 */ 212void journal_init(void); 213 214/* 215 * Call journal_create() to create a new journal. You only 216 * call this once, typically at file system creation time. 217 * 218 * The "jvp" argument is the vnode where the journal is written. 219 * The journal starts at "offset" and is "journal_size" bytes long. 220 * 221 * The "fsvp" argument is the vnode of your file system. It may be 222 * the same as "jvp". 223 * 224 * The "min_fs_block_size" argument is the minimum block size 225 * (in bytes) that the file system will ever write. Typically 226 * this is the block size of the file system (1k, 4k, etc) but 227 * on HFS+ it is the minimum block size of the underlying device. 228 * 229 * The flags argument lets you disable group commit if you 230 * want tighter guarantees on transactions (in exchange for 231 * lower performance). 232 * 233 * The tbuffer_size is the size of the transaction buffer 234 * used by the journal. If you specify zero, the journal code 235 * will use a reasonable defaults. The tbuffer_size should 236 * be an integer multiple of the min_fs_block_size. 237 * 238 * Returns a valid journal pointer or NULL if one could not 239 * be created. 240 */ 241journal *journal_create(struct vnode *jvp, 242 off_t offset, 243 off_t journal_size, 244 struct vnode *fsvp, 245 size_t min_fs_block_size, 246 int32_t flags, 247 int32_t tbuffer_size, 248 void (*flush)(void *arg), 249 void *arg, 250 struct mount *fsmount); 251 252/* 253 * Call journal_open() when mounting an existing file system 254 * that has a previously created journal. It will take care 255 * of validating the journal and replaying it if necessary. 256 * 257 * See journal_create() for a description of the arguments. 258 * 259 * Returns a valid journal pointer of NULL if it runs into 260 * trouble reading/playing back the journal. 261 */ 262journal *journal_open(struct vnode *jvp, 263 off_t offset, 264 off_t journal_size, 265 struct vnode *fsvp, 266 size_t min_fs_block_size, 267 int32_t flags, 268 int32_t tbuffer_size, 269 void (*flush)(void *arg), 270 void *arg, 271 struct mount *fsmount); 272 273/* 274 * Test whether the journal is clean or not. This is intended 275 * to be used when you're mounting read-only. If the journal 276 * is not clean for some reason then you should not mount the 277 * volume as your data structures may be in an unknown state. 278 */ 279int journal_is_clean(struct vnode *jvp, 280 off_t offset, 281 off_t journal_size, 282 struct vnode *fsvp, 283 size_t min_fs_block_size); 284 285 286/* 287 * Call journal_close() just before your file system is unmounted. 288 * It flushes any outstanding transactions and makes sure the 289 * journal is in a consistent state. 290 */ 291void journal_close(journal *journalp); 292 293/* 294 * flags for journal_create/open. only can use 295 * the low 16 bits for flags because internal 296 * bits go in the high 16. 297 */ 298#define JOURNAL_NO_GROUP_COMMIT 0x00000001 299#define JOURNAL_RESET 0x00000002 300 301/* 302 * Transaction related functions. 303 * 304 * Before you start modifying file system meta data, you 305 * should call journal_start_transaction(). Then before 306 * you modify each block, call journal_modify_block_start() 307 * and when you're done, journal_modify_block_end(). When 308 * you've modified the last block as part of a transaction, 309 * call journal_end_transaction() to commit the changes. 310 * 311 * If you decide to abort the modifications to a block you 312 * should call journal_modify_block_abort(). 313 * 314 * If as part of a transaction you need want to throw out 315 * any previous copies of a block (because it got deleted) 316 * then call journal_kill_block(). This will mark it so 317 * that the journal does not play it back (effectively 318 * dropping it). 319 * 320 * journal_trim_add_extent() marks a range of bytes on the device which should 321 * be trimmed (invalidated, unmapped). journal_trim_remove_extent() marks a 322 * range of bytes which should no longer be trimmed. Accumulated extents 323 * will be trimmed when the transaction is flushed to the on-disk journal. 324 */ 325int journal_start_transaction(journal *jnl); 326int journal_modify_block_start(journal *jnl, struct buf *bp); 327int journal_modify_block_abort(journal *jnl, struct buf *bp); 328int journal_modify_block_end(journal *jnl, struct buf *bp, void (*func)(struct buf *bp, void *arg), void *arg); 329int journal_kill_block(journal *jnl, struct buf *bp); 330#ifdef BSD_KERNEL_PRIVATE 331int journal_trim_add_extent(journal *jnl, uint64_t offset, uint64_t length); 332int journal_trim_remove_extent(journal *jnl, uint64_t offset, uint64_t length); 333void journal_trim_set_callback(journal *jnl, jnl_trim_callback_t callback, void *arg); 334int 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 */ 336int journal_request_immediate_flush (journal *jnl); 337#endif 338int journal_end_transaction(journal *jnl); 339 340int journal_active(journal *jnl); 341int journal_flush(journal *jnl, boolean_t wait_for_IO); 342void *journal_owner(journal *jnl); // compare against current_thread() 343int journal_uses_fua(journal *jnl); 344 345 346/* 347 * Relocate the journal. 348 * 349 * You provide the new starting offset and size for the journal. You may 350 * optionally provide a new tbuffer_size; passing zero defaults to not 351 * changing the tbuffer size except as needed to fit within the new journal 352 * size. 353 * 354 * You must have already started a transaction. The transaction may contain 355 * modified blocks (such as those needed to deallocate the old journal, 356 * allocate the new journal, and update the location and size of the journal 357 * in filesystem-private structures). Any transactions prior to the active 358 * transaction will be flushed to the old journal. The new journal will be 359 * initialized, and the blocks from the active transaction will be written to 360 * the new journal. The caller will need to update the structures that 361 * identify the location and size of the journal from the callback routine. 362 */ 363int journal_relocate(journal *jnl, off_t offset, off_t journal_size, int32_t tbuffer_size, 364 errno_t (*callback)(void *), void *callback_arg); 365 366__END_DECLS 367 368#endif /* __APPLE_API_UNSTABLE */ 369#endif /* !_SYS_VFS_JOURNAL_H_ */ 370