[apple/xnu.git] / bsd / vfs / vfs_journal.h


/*
 * Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
/*
 * This header contains the structures and function prototypes
 * for the vfs journaling code.  The data types are not meant
 * to be modified by user code.  Just use the functions and do
 * not mess around with the structs.
 */ 
#ifndef _SYS_VFS_JOURNAL_H_
#define _SYS_VFS_JOURNAL_H_

#include <sys/appleapiopts.h>

#ifdef __APPLE_API_UNSTABLE

#include <sys/types.h>
#include <sys/lock.h>

typedef struct block_info {
    off_t       bnum;                // block # on the file system device
    size_t      bsize;               // in bytes
    struct buf *bp;
} block_info;

typedef struct block_list_header {
    u_int16_t   max_blocks;          // max number of blocks in this chunk
    u_int16_t   num_blocks;          // number of valid block numbers in block_nums
    int32_t     bytes_used;          // how many bytes of this tbuffer are used
    int32_t     checksum;            // on-disk: checksum of this header and binfo[0]
    int32_t     pad;                 // pad out to 16 bytes
    block_info  binfo[1];            // so we can reference them by name
} block_list_header;


struct journal;

typedef struct transaction {
    int                 tbuffer_size;  // in bytes
    char               *tbuffer;       // memory copy of the transaction
    block_list_header  *blhdr;         // points to the first byte of tbuffer
    int                 num_blhdrs;    // how many buffers we've allocated
    int                 total_bytes;   // total # of bytes in transaction
    int                 num_flushed;   // how many bytes have been flushed
    int                 num_killed;    // how many bytes were "killed"
    off_t               journal_start; // where in the journal this transaction starts
    off_t               journal_end;   // where in the journal this transaction ends
    struct journal     *jnl;           // ptr back to the journal structure
    struct transaction *next;          // list of tr's (either completed or to be free'd)
} transaction;


/*
 * This is written to block zero of the journal and it
 * maintains overall state about the journal.
 */
typedef struct journal_header {
    int32_t        magic;
    int32_t        endian;
    volatile off_t start;         // zero-based byte offset of the start of the first transaction
    volatile off_t end;           // zero-based byte offset of where free space begins
    off_t          size;          // size in bytes of the entire journal
    int32_t        blhdr_size;    // size in bytes of each block_list_header in the journal
    int32_t        checksum;
    int32_t        jhdr_size;     // block size (in bytes) of the journal header
} journal_header;

#define JOURNAL_HEADER_MAGIC  0x4a4e4c78   // 'JNLx'
#define ENDIAN_MAGIC          0x12345678

#define OLD_JOURNAL_HEADER_MAGIC  0x4a484452   // 'JHDR'


/*
 * In memory structure about the journal.
 */
typedef struct journal {
	struct lock__bsd__	jlock;

    struct vnode       *jdev;              // vnode of the device where the journal lives
    off_t               jdev_offset;       // byte offset to the start of the journal

    struct vnode       *fsdev;             // vnode of the file system device
    
    void              (*flush)(void *arg); // fs callback to flush meta data blocks
    void               *flush_arg;         // arg that's passed to flush()

    int32_t             flags;
    int32_t             tbuffer_size;      // default transaction buffer size

    char               *header_buf;        // in-memory copy of the journal header
    journal_header     *jhdr;              // points to the first byte of header_buf

    transaction        *cur_tr;            // for group-commit
    transaction        *completed_trs;     // out-of-order transactions that completed
    transaction        *active_tr;         // for nested transactions
    int32_t             nested_count;      // for nested transactions
    void               *owner;             // a ptr that's unique to the calling process

    transaction        *tr_freeme;         // transaction structs that need to be free'd

	volatile off_t      active_start;      // the active start that we only keep in memory
	simple_lock_data_t  old_start_lock;    // guard access
	volatile off_t      old_start[16];     // this is how we do lazy start update

	int                 last_flush_err;    // last error from flushing the cache
} journal;

/* internal-only journal flags (top 16 bits) */
#define JOURNAL_CLOSE_PENDING     0x00010000
#define JOURNAL_INVALID           0x00020000
#define JOURNAL_FLUSHCACHE_ERR    0x00040000   // means we already printed this err
#define JOURNAL_NEED_SWAP         0x00080000   // swap any data read from disk

/* journal_open/create options are always in the low-16 bits */
#define JOURNAL_OPTION_FLAGS_MASK 0x0000ffff

/*
 * Prototypes.
 */

/*
 * Call journal_create() to create a new journal.  You only
 * call this once, typically at file system creation time.
 *
 * The "jvp" argument is the vnode where the journal is written.
 * The journal starts at "offset" and is "journal_size" bytes long.
 *
 * The "fsvp" argument is the vnode of your file system.  It may be
 * the same as "jvp".
 *
 * The "min_fs_block_size" argument is the minimum block size
 * (in bytes) that the file system will ever write.  Typically
 * this is the block size of the file system (1k, 4k, etc) but
 * on HFS+ it is the minimum block size of the underlying device.
 *
 * The flags argument lets you disable group commit if you
 * want tighter guarantees on transactions (in exchange for
 * lower performance).
 *
 * The tbuffer_size is the size of the transaction buffer
 * used by the journal. If you specify zero, the journal code
 * will use a reasonable defaults.  The tbuffer_size should 
 * be an integer multiple of the min_fs_block_size.
 *
 * Returns a valid journal pointer or NULL if one could not
 * be created.
 */
journal *journal_create(struct vnode *jvp,
						off_t         offset,
						off_t         journal_size,
						struct vnode *fsvp,
						size_t        min_fs_block_size,
						int32_t       flags,
						int32_t       tbuffer_size,
						void        (*flush)(void *arg),
						void         *arg);

/*
 * Call journal_open() when mounting an existing file system
 * that has a previously created journal.  It will take care
 * of validating the journal and replaying it if necessary.
 *
 * See journal_create() for a description of the arguments.
 *
 * Returns a valid journal pointer of NULL if it runs into
 * trouble reading/playing back the journal.
 */
journal  *journal_open(struct vnode *jvp,
					   off_t         offset,
					   off_t         journal_size,
					   struct vnode *fsvp,
					   size_t        min_fs_block_size,
					   int32_t       flags,
					   int32_t       tbuffer_size,
					   void        (*flush)(void *arg),
					   void         *arg);

/*
 * Call journal_close() just before your file system is unmounted.
 * It flushes any outstanding transactions and makes sure the
 * journal is in a consistent state.
 */
void      journal_close(journal *journal);

/*
 * flags for journal_create/open.  only can use 
 * the low 16 bits for flags because internal 
 * bits go in the high 16.
 */
#define JOURNAL_NO_GROUP_COMMIT   0x00000001
#define JOURNAL_RESET             0x00000002

/*
 * Transaction related functions.
 *
 * Before you start modifying file system meta data, you
 * should call journal_start_transaction().  Then before
 * you modify each block, call journal_modify_block_start()
 * and when you're done, journal_modify_block_end().  When
 * you've modified the last block as part of a transaction,
 * call journal_end_transaction() to commit the changes.
 *
 * If you decide to abort the modifications to a block you
 * should call journal_modify_block_abort().
 *
 * If as part of a transaction you need want to throw out
 * any previous copies of a block (because it got deleted)
 * then call journal_kill_block().  This will mark it so
 * that the journal does not play it back (effectively
 * dropping it).
 */
int   journal_start_transaction(journal *jnl);
int   journal_modify_block_start(journal *jnl, struct buf *bp);
int   journal_modify_block_abort(journal *jnl, struct buf *bp);
int   journal_modify_block_end(journal *jnl, struct buf *bp);
int   journal_kill_block(journal *jnl, struct buf *bp);
int   journal_end_transaction(journal *jnl);

int   journal_active(journal *jnl);
int   journal_flush(journal *jnl);

#endif /* __APPLE_API_UNSTABLE */
#endif /* !_SYS_VFS_JOURNAL_H_ */
Commit	Line	Data
b4c24cb9 A	1
	2	/*
	3	* Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved.
	4	*
	5	* @APPLE_LICENSE_HEADER_START@
	6	*
e5568f75 A	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.
b4c24cb9	12	*
e5568f75 A	13	* This Original Code and all software distributed under the License are
e5568f75 A	14	* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
b4c24cb9 A	15	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
b4c24cb9 A	16	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
e5568f75 A	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.
b4c24cb9 A	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>
55e303ae	37	#include <sys/lock.h>
b4c24cb9 A	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 {
55e303ae A	97	struct lock__bsd__ jlock;
55e303ae A	98
b4c24cb9 A	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
55e303ae	125	int last_flush_err; // last error from flushing the cache
b4c24cb9 A	126	} journal;
	127
	128	/* internal-only journal flags (top 16 bits) */
	129	#define JOURNAL_CLOSE_PENDING 0x00010000
	130	#define JOURNAL_INVALID 0x00020000
55e303ae A	131	#define JOURNAL_FLUSHCACHE_ERR 0x00040000 // means we already printed this err
55e303ae A	132	#define JOURNAL_NEED_SWAP 0x00080000 // swap any data read from disk
b4c24cb9 A	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_ */