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