Whamcloud - gitweb
ChangeLog, jfs.h, jfs_compat.h:
[tools/e2fsprogs.git] / include / linux / jfs.h
1 /*
2  * linux/include/linux/jfs.h
3  * 
4  * Written by Stephen C. Tweedie <sct@redhat.com>
5  *
6  * Copyright 1998-2000 Red Hat, Inc --- All Rights Reserved
7  *
8  * This file is part of the Linux kernel and is made available under
9  * the terms of the GNU General Public License, version 2, or at your
10  * option, any later version, incorporated herein by reference.
11  *
12  * Definitions for transaction data structures for the buffer cache
13  * filesystem journaling support.
14  */
15
16 #ifndef _LINUX_JFS_H
17 #define _LINUX_JFS_H
18
19 /* Allow this file to be included directly into e2fsprogs */
20 #ifndef __KERNEL__
21 #include "jfs_compat.h"
22 #endif
23
24 /*
25  * Debug code enabled by default for kernel builds
26  */
27 #ifdef __KERNEL__
28 #define JFS_DEBUG
29 #else
30 #define JFS_DEBUG
31 #endif
32
33 extern int journal_enable_debug;
34
35 #ifdef JFS_DEBUG
36 #define jfs_debug(n, f, a...)                                           \
37         do {                                                            \
38                 if ((n) <= journal_enable_debug) {                      \
39                         printk (KERN_DEBUG "JFS DEBUG: (%s, %d): %s: ", \
40                                 __FILE__, __LINE__, __FUNCTION__);      \
41                         printk (f, ## a);                               \
42                 }                                                       \
43         } while (0)
44 #else
45 #define jfs_debug(f, a...)      /**/
46 #endif
47
48 #define JFS_MIN_JOURNAL_BLOCKS 1024
49
50 /*
51  * Internal structures used by the logging mechanism:
52  */
53
54 #define JFS_MAGIC_NUMBER 0xc03b3998U /* The first 4 bytes of /dev/random! */
55
56
57 /*
58  * On-disk structures
59  */
60
61 /* 
62  * Descriptor block types:
63  */
64
65 #define JFS_DESCRIPTOR_BLOCK    1
66 #define JFS_COMMIT_BLOCK        2
67 #define JFS_SUPERBLOCK_V1       3
68 #define JFS_SUPERBLOCK_V2       4
69 #define JFS_REVOKE_BLOCK        5
70
71 /*
72  * Standard header for all descriptor blocks:
73  */
74 typedef struct journal_header_s
75 {
76         __u32           h_magic;
77         __u32           h_blocktype;
78         __u32           h_sequence;
79 } journal_header_t;
80
81
82 /* 
83  * The block tag: used to describe a single buffer in the journal 
84  */
85 typedef struct journal_block_tag_s
86 {
87         __u32           t_blocknr;      /* The on-disk block number */
88         __u32           t_flags;        /* See below */
89 } journal_block_tag_t;
90
91 /* 
92  * The revoke descriptor: used on disk to describe a series of blocks to
93  * be revoked from the log 
94  */
95 typedef struct journal_revoke_header_s
96 {
97         journal_header_t r_header;
98         int              r_count;       /* Count of bytes used in the block */
99 } journal_revoke_header_t;
100
101
102 /* Definitions for the journal tag flags word: */
103 #define JFS_FLAG_ESCAPE         1       /* on-disk block is escaped */
104 #define JFS_FLAG_SAME_UUID      2       /* block has same uuid as previous */
105 #define JFS_FLAG_DELETED        4       /* block deleted by this transaction */
106 #define JFS_FLAG_LAST_TAG       8       /* last tag in this descriptor block */
107
108
109 /*
110  * The journal superblock.  All fields are in big-endian byte order.
111  */
112 typedef struct journal_superblock_s
113 {
114 /* 0x0000 */
115         journal_header_t s_header;
116
117 /* 0x000C */
118         /* Static information describing the journal */
119         __u32   s_blocksize;            /* journal device blocksize */
120         __u32   s_maxlen;               /* total blocks in journal file */
121         __u32   s_first;                /* first block of log information */
122         
123 /* 0x0018 */
124         /* Dynamic information describing the current state of the log */
125         __u32   s_sequence;             /* first commit ID expected in log */
126         __u32   s_start;                /* blocknr of start of log */
127
128 /* 0x0020 */
129         /* Error value, as set by journal_abort(). */
130         __s32   s_errno;
131
132 /* 0x0024 */
133         /* Remaining fields are only valid in a version-2 superblock */
134         __u32   s_feature_compat;       /* compatible feature set */
135         __u32   s_feature_incompat;     /* incompatible feature set */
136         __u32   s_feature_ro_compat;    /* readonly-compatible feature set */
137 /* 0x0030 */
138         __u8    s_uuid[16];             /* 128-bit uuid for journal */
139
140 /* 0x0040 */
141         __u32   s_nr_users;             /* Nr of filesystems sharing log */
142         
143         __u32   s_dynsuper;             /* Blocknr of dynamic superblock copy*/
144         
145 /* 0x0048 */
146         __u32   s_max_transaction;      /* Limit of journal blocks per trans.*/
147         __u32   s_max_trans_data;       /* Limit of data blocks per trans. */
148
149 /* 0x0050 */
150         __u32   s_padding[44];
151
152 /* 0x0100 */
153         __u8    s_users[16*48];         /* ids of all fs'es sharing the log */
154 /* 0x0400 */
155 } journal_superblock_t;
156
157 #define JFS_HAS_COMPAT_FEATURE(j,mask)                                  \
158         ((j)->j_format_version >= 2 &&                                  \
159          ((j)->j_superblock->s_feature_compat & cpu_to_be32((mask))))
160 #define JFS_HAS_RO_COMPAT_FEATURE(j,mask)                               \
161         ((j)->j_format_version >= 2 &&                                  \
162          ((j)->j_superblock->s_feature_ro_compat & cpu_to_be32((mask))))
163 #define JFS_HAS_INCOMPAT_FEATURE(j,mask)                                \
164         ((j)->j_format_version >= 2 &&                                  \
165          ((j)->j_superblock->s_feature_incompat & cpu_to_be32((mask))))
166
167 #define JFS_FEATURE_INCOMPAT_REVOKE     0x00000001
168
169 /* Features known to this kernel version: */
170 #define JFS_KNOWN_COMPAT_FEATURES       0
171 #define JFS_KNOWN_ROCOMPAT_FEATURES     0
172 #define JFS_KNOWN_INCOMPAT_FEATURES     JFS_FEATURE_INCOMPAT_REVOKE
173
174 #ifdef __KERNEL__
175
176 #include <linux/fs.h>
177
178
179 #define J_ASSERT(assert)                                                \
180         do { if (!(assert)) {                                           \
181                 printk (KERN_EMERG                                      \
182                         "Assertion failure in %s() at %s line %d: "     \
183                         "\"%s\"\n",                                     \
184                         __FUNCTION__, __FILE__, __LINE__, # assert);    \
185                 * ((char *) 0) = 0;                                     \
186         } } while (0)
187
188
189 struct jfs_revoke_table_s;
190
191 /* The handle_t type represents a single atomic update being performed
192  * by some process.  All filesystem modifications made by the process go
193  * through this handle.  Recursive operations (such as quota operations)
194  * are gathered into a single update.
195  *
196  * The buffer credits field is used to account for journaled buffers
197  * being modified by the running process.  To ensure that there is
198  * enough log space for all outstanding operations, we need to limit the
199  * number of outstanding buffers possible at any time.  When the
200  * operation completes, any buffer credits not used are credited back to
201  * the transaction, so that at all times we know how many buffers the
202  * outstanding updates on a transaction might possibly touch. */
203
204 struct handle_s 
205 {
206         /* Which compound transaction is this update a part of? */
207         transaction_t         * h_transaction;
208
209         /* Number of remaining buffers we are allowed to dirty: */
210         int                     h_buffer_credits;
211
212         /* Reference count on this handle */
213         int                     h_ref;
214
215         /* Flags */
216         unsigned int            h_sync  : 1;    /* sync-on-close */
217         unsigned int            h_jdata : 1;    /* force data journaling */
218 };
219
220
221 /* The transaction_t type is the guts of the journaling mechanism.  It
222  * tracks a compound transaction through its various states:
223  *
224  * RUNNING:     accepting new updates
225  * LOCKED:      Updates still running but we don't accept new ones
226  * RUNDOWN:     Updates are tidying up but have finished requesting
227  *              new buffers to modify (state not used for now)
228  * FLUSH:       All updates complete, but we are still writing to disk
229  * COMMIT:      All data on disk, writing commit record
230  * FINISHED:    We still have to keep the transaction for checkpointing.
231  *
232  * The transaction keeps track of all of the buffers modified by a
233  * running transaction, and all of the buffers committed but not yet
234  * flushed to home for finished transactions.
235  */
236
237 struct transaction_s 
238 {
239         /* Pointer to the journal for this transaction. */
240         journal_t *             t_journal;
241         
242         /* Sequence number for this transaction */
243         tid_t                   t_tid;
244         
245         /* Transaction's current state */
246         enum {
247                 T_RUNNING,
248                 T_LOCKED,
249                 T_RUNDOWN,
250                 T_FLUSH,
251                 T_COMMIT,
252                 T_FINISHED 
253         }                       t_state;
254
255         /* Where in the log does this transaction's commit start? */
256         unsigned long           t_log_start;
257         
258         /* Doubly-linked circular list of all inodes owned by this
259            transaction */
260         struct inode *          t_ilist;
261         
262         /* Number of buffers on the t_buffers list */
263         int                     t_nr_buffers;
264         
265         /* Doubly-linked circular list of all buffers reserved but not
266            yet modified by this transaction */
267         struct buffer_head *    t_reserved_list;
268         
269         /* Doubly-linked circular list of all metadata buffers owned by this
270            transaction */
271         struct buffer_head *    t_buffers;
272         
273         /* Doubly-linked circular list of all data buffers still to be
274            flushed before this transaction can be committed */
275         struct buffer_head *    t_datalist;
276         
277         /* Doubly-linked circular list of all forget buffers (superceded
278            buffers which we can un-checkpoint once this transaction
279            commits) */
280         struct buffer_head *    t_forget;
281         
282         /* Doubly-linked circular list of all buffers still to be
283            flushed before this transaction can be checkpointed */
284         struct buffer_head *    t_checkpoint_list;
285         
286         /* Doubly-linked circular list of temporary buffers currently
287            undergoing IO in the log */
288         struct buffer_head *    t_iobuf_list;
289         
290         /* Doubly-linked circular list of metadata buffers being
291            shadowed by log IO.  The IO buffers on the iobuf list and the
292            shadow buffers on this list match each other one for one at
293            all times. */
294         struct buffer_head *    t_shadow_list;
295         
296         /* Doubly-linked circular list of control buffers being written
297            to the log. */
298         struct buffer_head *    t_log_list;
299         
300         /* Number of outstanding updates running on this transaction */
301         int                     t_updates;
302
303         /* Number of buffers reserved for use by all handles in this
304          * transaction handle but not yet modified. */
305         int                     t_outstanding_credits;
306         
307         /* Forward and backward links for the circular list of all
308          * transactions awaiting checkpoint */
309         transaction_t           *t_cpnext, *t_cpprev;
310
311         /* When will the transaction expire (become due for commit), in
312          * jiffies ? */
313         unsigned long           t_expires;
314 };
315
316
317 /* The journal_t maintains all of the journaling state information for a
318  * single filesystem.  It is linked to from the fs superblock structure.
319  * 
320  * We use the journal_t to keep track of all outstanding transaction
321  * activity on the filesystem, and to manage the state of the log
322  * writing process. */
323
324 struct journal_s
325 {
326         /* General journaling state flags */
327         unsigned long           j_flags;
328
329         /* Is there an outstanding uncleared error on the journal (from
330          * a prior abort)? */
331         int                     j_errno;
332         
333         /* The superblock buffer */
334         struct buffer_head *    j_sb_buffer;
335         journal_superblock_t *  j_superblock;
336
337         /* Version of the superblock format */
338         int                     j_format_version;
339
340         /* Number of processes waiting to create a barrier lock */
341         int                     j_barrier_count;
342         
343         /* The barrier lock itself */
344         struct semaphore        j_barrier;
345         
346         /* Transactions: The current running transaction... */
347         transaction_t *         j_running_transaction;
348         
349         /* ... the transaction we are pushing to disk ... */
350         transaction_t *         j_committing_transaction;
351         
352         /* ... and a linked circular list of all transactions waiting
353          * for checkpointing. */
354         transaction_t *         j_checkpoint_transactions;
355
356         /* Wait queue for locking of the journal structure.  */
357         struct wait_queue *     j_wait_lock;
358
359         /* Wait queue for waiting for a locked transaction to start
360            committing, or for a barrier lock to be released */
361         struct wait_queue *     j_wait_transaction_locked;
362         
363         /* Wait queue for waiting for checkpointing to complete */
364         struct wait_queue *     j_wait_logspace;
365         
366         /* Wait queue for waiting for commit to complete */
367         struct wait_queue *     j_wait_done_commit;
368         
369         /* Wait queue to trigger checkpointing */
370         struct wait_queue *     j_wait_checkpoint;
371         
372         /* Wait queue to trigger commit */
373         struct wait_queue *     j_wait_commit;
374         
375         /* Wait queue to wait for updates to complete */
376         struct wait_queue *     j_wait_updates;
377
378         /* Semaphore for locking against concurrent checkpoints */
379         struct semaphore        j_checkpoint_sem;
380                 
381         /* Journal running state: */
382         /* The lock flag is *NEVER* touched from interrupts. */
383         unsigned int            j_locked : 1;
384
385         /* Journal head: identifies the first unused block in the journal. */
386         unsigned long           j_head;
387         
388         /* Journal tail: identifies the oldest still-used block in the
389          * journal. */
390         unsigned long           j_tail;
391
392         /* Journal free: how many free blocks are there in the journal? */
393         unsigned long           j_free;
394
395         /* Journal start and end: the block numbers of the first usable
396          * block and one beyond the last usable block in the journal. */
397         unsigned long           j_first, j_last;
398
399         /* Device, blocksize and starting block offset for the location
400          * where we store the journal. */
401         kdev_t                  j_dev;
402         int                     j_blocksize;
403         unsigned int            j_blk_offset;
404
405         /* Total maximum capacity of the journal region on disk. */
406         unsigned int            j_maxlen;
407
408         /* Optional inode where we store the journal.  If present, all
409          * journal block numbers are mapped into this inode via
410          * bmap(). */
411         struct inode *          j_inode;
412
413         /* Sequence number of the oldest transaction in the log */
414         tid_t                   j_tail_sequence;
415         /* Sequence number of the next transaction to grant */
416         tid_t                   j_transaction_sequence;
417         /* Sequence number of the most recently committed transaction */
418         tid_t                   j_commit_sequence;
419         /* Sequence number of the most recent transaction wanting commit */
420         tid_t                   j_commit_request;
421
422         /* Journal uuid: identifies the object (filesystem, LVM volume
423          * etc) backed by this journal.  This will eventually be
424          * replaced by an array of uuids, allowing us to index multiple
425          * devices within a single journal and to perform atomic updates
426          * across them.  */
427
428         __u8                    j_uuid[16];
429
430         /* Pointer to the current commit thread for this journal */
431         struct task_struct *    j_task;
432
433         /* Maximum number of metadata buffers to allow in a single
434          * compound commit transaction */
435         int                     j_max_transaction_buffers;
436
437         /* What is the maximum transaction lifetime before we begin a
438          * commit? */
439         unsigned long           j_commit_interval;
440
441         /* The timer used to wakeup the commit thread: */
442         struct timer_list *     j_commit_timer;
443         int                     j_commit_timer_active;
444
445         /* The revoke table: maintains the list of revoked blocks in the
446            current transaction. */
447         struct jfs_revoke_table_s *j_revoke;
448 };
449
450 /* 
451  * Journal flag definitions 
452  */
453 #define JFS_UNMOUNT     0x001   /* Journal thread is being destroyed */
454 #define JFS_SYNC        0x002   /* Perform synchronous transaction commits */
455 #define JFS_ABORT       0x004   /* Journaling has been aborted for errors. */
456 #define JFS_ACK_ERR     0x008   /* The errno in the sb has been acked */
457 #define JFS_FLUSHED     0x010   /* The journal superblock has been flushed */
458 #define JFS_LOADED      0x020   /* The journal superblock has been loaded */
459
460 /* 
461  * Journaling internal variables/parameters 
462  */
463
464 extern int journal_flush_nr_buffers;
465
466
467 /* 
468  * Function declarations for the journaling transaction and buffer
469  * management
470  */
471
472 /* Filing buffers */
473 extern void journal_unfile_buffer(struct buffer_head *);
474 extern void journal_refile_buffer(struct buffer_head *);
475 extern void journal_file_buffer(struct buffer_head *, transaction_t *, int);
476 extern void journal_clean_data_list(transaction_t *transaction);
477
478 /* Log buffer allocation */
479 extern struct buffer_head * journal_get_descriptor_buffer(journal_t *);
480 extern unsigned long journal_next_log_block(journal_t *);
481
482 /* Commit management */
483 extern void journal_commit_transaction(journal_t *);
484
485 /* Checkpoint list management */
486 extern void journal_remove_checkpoint(struct buffer_head *);
487 extern void journal_insert_checkpoint(struct buffer_head *, transaction_t *);
488
489 /* Buffer IO */
490 extern int 
491 journal_write_metadata_buffer(transaction_t       *transaction,
492                               struct buffer_head  *bh_in,
493                               struct buffer_head **bh_out,
494                               int                  blocknr);
495
496 /* Create and destroy transactions */
497 extern transaction_t *  get_transaction (journal_t *);
498 extern void             put_transaction (transaction_t *);
499
500 /* Notify state transitions (called by the log writer thread): */
501 extern int              set_transaction_state (transaction_t *, int);
502
503
504 /* Transaction locking */
505 extern void             __wait_on_journal (journal_t *);
506
507 /* Journal locking.  In 2.2, we assume that the kernel lock is already
508  * held. */
509 static inline void lock_journal (journal_t * journal)
510 {
511 #ifdef __SMP__
512         J_ASSERT(current->lock_depth >= 0);
513 #endif
514         if (journal->j_locked)
515                 __wait_on_journal(journal);
516         journal->j_locked = 1;
517 }
518
519 static inline int try_lock_journal (journal_t * journal)
520 {
521         if (journal->j_locked)
522                 return 1;
523         journal->j_locked = 1;
524         return 0;
525 }
526
527 static inline void unlock_journal (journal_t * journal)
528 {
529         J_ASSERT (journal->j_locked);
530         journal->j_locked = 0;
531         wake_up(&journal->j_wait_lock);
532 }
533
534 /* This function is gross, but unfortunately we need it as long as
535  * existing filesystems want to guard against races by testing
536  * bh->b_count.  @@@ Remove this?  We no longer abuse b_count so badly!
537  */
538
539 static inline int journal_is_buffer_shared(struct buffer_head *bh)
540 {
541         int count = bh->b_count;
542         J_ASSERT (count >= 1);
543         return (count > 1);
544 }
545
546 /* The journaling code user interface:
547  *
548  * Create and destroy handles
549  * Register buffer modifications against the current transaction. 
550  */
551
552 extern handle_t *journal_start (journal_t *, int nblocks);
553 extern int       journal_restart (handle_t *, int nblocks);
554 extern int       journal_extend (handle_t *, int nblocks);
555 extern int       journal_get_write_access (handle_t *, struct buffer_head *);
556 extern int       journal_get_create_access (handle_t *, struct buffer_head *);
557 extern int       journal_get_undo_access (handle_t *, struct buffer_head *);
558 extern int       journal_dirty_data (handle_t *, struct buffer_head *);
559 extern int       journal_dirty_metadata (handle_t *, struct buffer_head *);
560 extern void      journal_release_buffer (handle_t *, struct buffer_head *);
561 extern void      journal_forget (handle_t *, struct buffer_head *);
562 extern void      journal_sync_buffer (struct buffer_head *);
563 extern int       journal_stop (handle_t *);
564 extern int       journal_flush (journal_t *);
565
566 extern void      journal_lock_updates (journal_t *);
567 extern void      journal_unlock_updates (journal_t *);
568
569 extern journal_t * journal_init_dev   (kdev_t, int start, int len, int bsize);
570 extern journal_t * journal_init_inode (struct inode *);
571 extern int         journal_update_format (journal_t *);
572 extern int         journal_check_used_features 
573                    (journal_t *, unsigned long, unsigned long, unsigned long);
574 extern int         journal_check_available_features 
575                    (journal_t *, unsigned long, unsigned long, unsigned long);
576 extern int         journal_set_features 
577                    (journal_t *, unsigned long, unsigned long, unsigned long);
578 extern int         journal_create     (journal_t *);
579 extern int         journal_load       (journal_t *);
580 extern void        journal_release    (journal_t *);
581 extern int         journal_wipe       (journal_t *, int);
582 extern int         journal_skip_recovery (journal_t *);
583 extern void        journal_update_superblock (journal_t *, int);
584 extern void        __journal_abort      (journal_t *);
585 extern void        journal_abort      (journal_t *, int);
586 extern int         journal_errno      (journal_t *);
587 extern void        journal_ack_err    (journal_t *);
588 extern int         journal_clear_err  (journal_t *);
589
590 /* Primary revoke support */
591 #define JOURNAL_REVOKE_DEFAULT_HASH 256
592 extern int         journal_revoke (handle_t *, unsigned long, struct buffer_head *);
593 extern void        journal_cancel_revoke(handle_t *, struct buffer_head *);
594 extern void        journal_write_revoke_records(journal_t *, transaction_t *);
595
596
597
598 /* The log thread user interface:
599  *
600  * Request space in the current transaction, and force transaction commit
601  * transitions on demand.
602  */
603
604 extern int      log_space_left (journal_t *); /* Called with journal locked */
605 extern void     log_start_commit (journal_t *, transaction_t *);
606 extern void     log_wait_commit (journal_t *, tid_t);
607 extern int      log_do_checkpoint (journal_t *, int);
608
609 extern void     log_wait_for_space(journal_t *, int nblocks);
610 extern void     journal_drop_transaction(journal_t *, transaction_t *);
611 extern int      cleanup_journal_tail(journal_t *);
612
613
614 /* Debugging code only: */
615
616 #define jfs_ENOSYS() \
617 do {                                                                  \
618         printk (KERN_ERR "JFS unimplemented function " __FUNCTION__); \
619         current->state = TASK_UNINTERRUPTIBLE;                        \
620         schedule();                                                   \
621 } while (1)
622
623 /*
624  * is_journal_abort
625  *
626  * Simple test wrapper function to test the JFS_ABORT state flag.  This
627  * bit, when set, indicates that we have had a fatal error somewhere,
628  * either inside the journaling layer or indicated to us by the client
629  * (eg. ext3), and that we and should not commit any further
630  * transactions.  
631  */
632
633 static inline int is_journal_abort(journal_t *journal)
634 {
635         return journal->j_flags & JFS_ABORT;
636 }
637
638 /* Not all architectures define BUG() */
639 #ifndef BUG
640 # define BUG() do { \
641         printk("kernel BUG at %s:%d!\n", __FILE__, __LINE__); \
642         * ((char *) 0) = 0; \
643  } while (0)
644 #endif /* BUG */
645
646 #endif /* __KERNEL__   */
647
648 /* Function prototypes, used by both user- and kernel- space */
649
650 /* recovery.c */
651 extern int         journal_recover    (journal_t *);
652
653 /* revoke.c */
654 extern int         journal_init_revoke(journal_t *, int);
655 extern int         journal_set_revoke(journal_t *, unsigned long, tid_t);
656 extern int         journal_test_revoke(journal_t *, unsigned long, tid_t);
657 extern void        journal_clear_revoke(journal_t *);
658 extern void        journal_destroy_revoke(journal_t *);
659
660
661 /* Comparison functions for transaction IDs: perform comparisons using
662  * modulo arithmetic so that they work over sequence number wraps. */
663
664 static inline int tid_ge(tid_t x, tid_t y)
665 {
666         int difference = (x - y);
667         return (difference > 0);
668 }
669
670 static inline int tid_geq(tid_t x, tid_t y)
671 {
672         int difference = (x - y);
673         return (difference >= 0);
674 }
675
676
677 #endif /* _LINUX_JFS_H */