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