xnu-344.49.tar.gz
[apple/xnu.git] / bsd / vfs / vfs_journal.h
0 / 241 (  0%)
CommitLineData
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
41typedef 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
47typedef 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
57struct journal;
58
59typedef 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 */
78typedef 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 */
98typedef 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 */
166journal *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 */
186journal *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 */
201void 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 */
230int journal_start_transaction(journal *jnl);
231int journal_modify_block_start(journal *jnl, struct buf *bp);
232int journal_modify_block_abort(journal *jnl, struct buf *bp);
233int journal_modify_block_end(journal *jnl, struct buf *bp);
234int journal_kill_block(journal *jnl, struct buf *bp);
235int journal_end_transaction(journal *jnl);
236
237int journal_active(journal *jnl);
238int journal_flush(journal *jnl);
239
240#endif /* __APPLE_API_UNSTABLE */
241#endif /* !_SYS_VFS_JOURNAL_H_ */