FreeBSD/Linux Kernel Cross Reference
sys/sys/journal.h

     /*
      * Copyright (c) 2004 The DragonFly Project.  All rights reserved.
      * 
      * This code is derived from software contributed to The DragonFly Project
      * by Matthew Dillon <dillon@backplane.com>
      * 
      * Redistribution and use in source and binary forms, with or without
      * modification, are permitted provided that the following conditions
      * are met:
     * 
     * 1. Redistributions of source code must retain the above copyright
     *    notice, this list of conditions and the following disclaimer.
     * 2. Redistributions in binary form must reproduce the above copyright
     *    notice, this list of conditions and the following disclaimer in
     *    the documentation and/or other materials provided with the
     *    distribution.
     * 3. Neither the name of The DragonFly Project nor the names of its
     *    contributors may be used to endorse or promote products derived
     *    from this software without specific, prior written permission.
     * 
     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
     * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
     * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
     * INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
     * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
     * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
     * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
     * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
     * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
     * SUCH DAMAGE.
     *
     * $DragonFly: src/sys/sys/journal.h,v 1.13 2007/05/09 00:53:35 dillon Exp $
     */
    
    #ifndef _SYS_JOURNAL_H_
    #define _SYS_JOURNAL_H_
    
    #ifndef _SYS_TYPES_H_
    #include <sys/types.h>
    #endif
    #ifndef _SYS_TIME_H_
    #include <sys/time.h>
    #endif
    
    /*
     * Physical file format (binary)
     *
     * All raw records are 128-bit aligned, but all record sizes are actual.
     * This means that any scanning code must 16-byte-align the recsize field
     * when calculating skips.  The top level raw record has a header and a
     * trailer to allow both forwards and backwards scanning of the journal.
     * The alignment requirement allows the worker thread FIFO reservation
     * API to operate efficiently, amoung other things.
     *
     * Logical data stream records are usually no larger then the journal's
     * in-memory FIFO, since the journal's transactional APIs return contiguous
     * blocks of buffer space and since logical stream records are used to avoid
     * stalls when concurrent blocking operations are being written to the journal.
     * Programs can depend on a logical stream record being a 'reasonable' size.
     *
     * Multiple logical data streams may operate concurrently in the journal,
     * reflecting the fact that the system may be executing multiple blocking
     * operations on the filesystem all at the same time.  These logical data
     * streams are short-lived transactional entities which use a 13 bit id
     * plus a transaction start bit, end bit, and abort bit.
     *
     * Stream identifiers in the 0x00-0xFF range are special and not used for
     * normal transactional commands. 
     *
     * Stream id 0x00 indicates that no other streams should be active at that
     * point in the journal, which helps the journaling code detect corruption.
     *
     * Stream id 0x01 is used for pad.  Pads are used to align data on convenient
     * boundaries and to deal with dead space.
     *
     * Stream id 0x02 indicates a discontinuity in the streamed data and typically
     * contains information relating to the reason for the discontinuity.
     * JTYPE_ASSOCIATE and JTYPE_DISASSOCIATE are usually emplaced in stream 0x02.
     *
     * Stream id 0x03 may be used to annotate the journal with text comments
     * via mountctl commands.  This can be extremely useful to note situations
     * that may help with later recovery or audit operations.
     *
     * Stream id 0x04-0x7F are reserved by DragonFly for future protocol expansion.
     *
     * Stream id 0x80-0xFF may be used for third-party protocol expansion.
     *
     * Stream id's 0x0100-0x1FFF typically represent short-lived transactions
     * (i.e. an id may be reused once the previous use has completed).  The
     * journaling system runs through these id's sequentially which means that
     * the journaling code can handle up to 8192-256 = 7936 simultanious
     * transactions at any given moment.
     *
     * The sequence number field is context-sensitive.  It is typically used by
     * a journaling stream to provide an incrementing counter and/or timestamp
     * so recovery utilities can determine if any data is missing.
     *
    * The check word in the trailer may be used to provide an integrity check
    * on the journaled data.  A value of 0 always means that no check word
    * has been calculated.
    *
    * The journal_rawrecbeg structure MUST be a multiple of 16 bytes.
    * The journal_rawrecend structure MUST be a multiple of 8 bytes.
    *
    * NOTE: PAD RECORD SPECIAL CASE.  Pad records can be 16 bytes and have the
    * rawrecend structure overlayed on the sequence number field of the 
    * rawrecbeg structure.  This is necessary because stream records are
    * 16 byte aligned, not 24 byte aligned, and dead space is not allowed.
    * So the pad record must fit into any dead space.  THEREFORE, THE TRANSID
    * FIELD FOR A PAD RECORD MUST BE IGNORED.
    *
    * NOTE: ENDIAN HANDLING.  Data records can be in little or big endian form.
    * The receiver detects the state by observing the 'begmagic' field.  Each
    * direction in a full-duplex connection can be operating with different
    * endianess.  Checksum data is always calculated on the raw record (including
    * dead space) in a byte-stream fashion, and then converted to the transmit
    * endianess like everything else.  If the receiver's endianess is different
    * it must convert it back to host normal form to compare it against the
    * calculated checksum.
    */
   struct journal_rawrecbeg {
           u_int16_t begmagic;     /* recovery scan, endianess detection */
           u_int16_t streamid;     /* start/stop bits and stream identifier */
           int32_t recsize;        /* stream data block (incls beg & end) */
           int64_t transid;        /* sequence number or transaction id */
           /* ADDITIONAL DATA */
   };
   
   struct journal_rawrecend {
           u_int16_t endmagic;     /* recovery scan, endianess detection */
           u_int16_t check;        /* check word or 0 */
           int32_t recsize;        /* same as rawrecbeg->recsize, for rev scan */
   };
   
   struct journal_ackrecord {
           struct journal_rawrecbeg        rbeg;
           int32_t                         filler0;
           int32_t                         filler1;
           struct journal_rawrecend        rend;
   };
   
   /*
    * Constants for stream record magic numbers.    The incomplete magic
    * number code is used internally by the memory FIFO reservation API
    * and worker thread, allowing a block of space in the journaling
    * stream (aka a stream block) to be reserved and then populated without
    * stalling other threads doing their own reservation and population.
    */
   #define JREC_BEGMAGIC           0x1234
   #define JREC_ENDMAGIC           0xCDEF
   #define JREC_INCOMPLETEMAGIC    0xFFFF
   
   /*
    * Stream ids are 14 bits.  The top 2 bits specify when a new logical
    * stream is being created or an existing logical stream is being terminated.
    * A single raw stream record will set both the BEGIN and END bits if the
    * entire transaction is encapsulated in a single stream record.
    */
   #define JREC_STREAMCTL_MASK     0xE000
   #define JREC_STREAMCTL_BEGIN    0x8000  /* start a new logical stream */
   #define JREC_STREAMCTL_END      0x4000  /* terminate a logical stream */
   #define JREC_STREAMCTL_ABORTED  0x2000
   
   #define JREC_STREAMID_MASK      0x1FFF
   #define JREC_STREAMID_SYNCPT    (JREC_STREAMCTL_BEGIN|JREC_STREAMCTL_END|0x0000)
   #define JREC_STREAMID_PAD       (JREC_STREAMCTL_BEGIN|JREC_STREAMCTL_END|0x0001)
   #define JREC_STREAMID_DISCONT   0x0002  /* discontinuity */
   #define JREC_STREAMID_ANNOTATE  0x0003  /* annotation */
   #define JREC_STREAMID_ACK       0x0004  /* acknowledgement */
   #define JREC_STREAMID_RESTART   0x0005  /* disctoninuity - journal restart */
                                   /* 0x0006-0x007F reserved by DragonFly */
                                   /* 0x0080-0x00FF for third party use */
   #define JREC_STREAMID_JMIN      0x0100  /* lowest allowed general id */
   #define JREC_STREAMID_JMAX      0x2000  /* (one past the highest allowed id) */
   
   #define JREC_DEFAULTSIZE        64      /* reasonable initial reservation */
   #define JREC_MINRECSIZE         16      /* (after alignment) */
   #define JREC_MAXRECSIZE         (128*1024*1024)
   
   /*
    * Each logical journaling stream typically represents a transaction...
    * that is, a VFS operation.  The VFS operation is written out using 
    * sub-records and may contain multiple, possibly nested sub-transactions.
    * multiple sub-transactions occur when a VFS operation cannot be represented
    * by a single command.  This is typically the case when a journal is 
    * configured to be reversable because UNDO sequences almost always have to
    * be specified in such cases.  For example, if you ftruncate() a file the
    * journal might have to write out a sequence of WRITE records representing
    * the lost data, otherwise the journal would not be reversable.
    * Sub-transactions within a particular stream do not have their own sequence
    * number field and thus may not be parallelized (the protocol is already
    * complex enough!).
    *
    * In order to support streaming operation with a limited buffer the recsize
    * field is allowed to be 0 for subrecords with the JMASK_NESTED bit set.
    * If this case occurs a scanner can determine that the recursion has ended
    * by detecting a nested subrecord with the JMASK_LAST bit set.  A scanner
    * may also set the field to the proper value after the fact to make later
    * operations more efficient. 
    *
    * Note that this bit must be properly set even if the recsize field is
    * non-zero.  The recsize must always be properly specified for 'leaf'
    * subrecords, however in order to allow subsystems to potentially allocate
    * more data space then they use the protocol allows any 'dead' space to be
    * filled with JLEAF_PAD records.
    *
    * The recsize field may indicate data well past the size of the current
    * raw stream record.  That is, the scanner may have to glue together
    * multiple stream records with the same stream id to fully decode the
    * embedded subrecords.  In particular, a subrecord could very well represent
    * hundreds of megabytes of data (e.g. if a program were to do a
    * multi-megabyte write()) and be split up across thousands of raw streaming
    * records, possibly interlaced with other unrelated streams from other
    * unrelated processes.  
    *
    * If a large sub-transaction is aborted the logical stream may be
    * terminated without writing out all the expected data.  When this occurs
    * the stream's ending record must also have the JREC_STREAMCTL_ABORTED bit
    * set.  However, scanners should still be robust enough to detect such
    * overflows even if the aborted bit is not set and consider them data
    * corruption.
    * 
    * Aborts may also occur in the normal course of operations, especially once
    * the journaling API is integrated into the cache coherency API.  A normal
    * abort is issued by emplacing a JLEAF_ABORT record within the transaction
    * being aborted.  Such records must be the last record in the sub-transaction,
    * so JLEAF_LAST is also usually set.  In a transaction with many 
    * sub-transactions only those sub-transactions with an abort record are
    * aborted, the rest remain valid.  Abort records are considered S.O.P. for
    * two reasons:  First, limited memory buffer space may make it impossible
    * to delete the portion of the stream being aborted (the data may have
    * already been sent to the target).  Second, the journaling code will
    * eventually be used to support a cache coherency layer which may have to
    * abort operations as part of the cache coherency protocol.  Note that
    * subrecord aborts are different from stream record aborts.  Stream record
    * aborts are considered to be extrodinary situations while subrecord aborts
    * are S.O.P.
    */
   
   struct journal_subrecord {
           u_int16_t rectype;      /* 2 control bits, 14 record type bits */
           int16_t reserved;       /* future use */
           int32_t recsize;        /* record size (mandatory if not NESTED) */
           /* ADDITIONAL DATA */
   };
   
   #define JDATA_KERN              0x0001
   #define JDATA_USER              0x0002
   #define JDATA_XIO               0x0003
   
   #define JMASK_NESTED            0x8000  /* data is a nested recursion */
   #define JMASK_LAST              0x4000
   #define JMASK_SUBRECORD         0x0400
   #define JTYPE_MASK              (~JMASK_LAST)
   
   #define JLEAF_PAD               0x0000
   #define JLEAF_ABORT             0x0001
   #define JTYPE_ASSOCIATE         0x0002
   #define JTYPE_DISASSOCIATE      0x0003
   #define JTYPE_UNDO              (JMASK_NESTED|0x0004)
   #define JTYPE_AUDIT             (JMASK_NESTED|0x0005)
   #define JTYPE_REDO              (JMASK_NESTED|0x0006)
   
   #define JTYPE_SETATTR           (JMASK_NESTED|0x0010)
   #define JTYPE_WRITE             (JMASK_NESTED|0x0011)
   #define JTYPE_PUTPAGES          (JMASK_NESTED|0x0012)
   #define JTYPE_SETACL            (JMASK_NESTED|0x0013)
   #define JTYPE_SETEXTATTR        (JMASK_NESTED|0x0014)
   #define JTYPE_CREATE            (JMASK_NESTED|0x0015)
   #define JTYPE_MKNOD             (JMASK_NESTED|0x0016)
   #define JTYPE_LINK              (JMASK_NESTED|0x0017)
   #define JTYPE_SYMLINK           (JMASK_NESTED|0x0018)
   #define JTYPE_WHITEOUT          (JMASK_NESTED|0x0019)
   #define JTYPE_REMOVE            (JMASK_NESTED|0x001A)
   #define JTYPE_MKDIR             (JMASK_NESTED|0x001B)
   #define JTYPE_RMDIR             (JMASK_NESTED|0x001C)
   #define JTYPE_RENAME            (JMASK_NESTED|0x001D)
   
   #define JTYPE_VATTR             (JMASK_NESTED|0x0100)
   #define JTYPE_CRED              (JMASK_NESTED|0x0101)
   
   /*
    * Low level record types
    */
   #define JLEAF_FILEDATA          0x0401
   #define JLEAF_PATH1             0x0402
   #define JLEAF_PATH2             0x0403
   #define JLEAF_PATH3             0x0404
   #define JLEAF_PATH4             0x0405
   #define JLEAF_UID               0x0406
   #define JLEAF_GID               0x0407
   #define JLEAF_MODES             0x0408
   #define JLEAF_FFLAGS            0x0409
   #define JLEAF_PID               0x040A
   #define JLEAF_PPID              0x040B
   #define JLEAF_COMM              0x040C
   #define JLEAF_ATTRNAME          0x040D
   #define JLEAF_PATH_REF          0x040E
   #define JLEAF_RESERVED_0F       0x040F
   #define JLEAF_SYMLINKDATA       0x0410
   #define JLEAF_SEEKPOS           0x0411
   #define JLEAF_INUM              0x0412
   #define JLEAF_NLINK             0x0413
   #define JLEAF_FSID              0x0414
   #define JLEAF_SIZE              0x0415
   #define JLEAF_ATIME             0x0416
   #define JLEAF_MTIME             0x0417
   #define JLEAF_CTIME             0x0418
   #define JLEAF_GEN               0x0419
   #define JLEAF_FLAGS             0x041A
   #define JLEAF_UDEV              0x041B
   #define JLEAF_FILEREV           0x041C
   #define JLEAF_VTYPE             0x041D
   #define JLEAF_ERROR             0x041E
   #define JLEAF_UMAJOR            0x041F
   #define JLEAF_UMINOR            0x0420
   
   /*
    * Low level journal data file structures
    *
    * NOTE: embedded strings may use the full width of the field and thus
    * may not be 0-terminated.
    */
   struct jleaf_path {
           char    path[4];        /* path from base of mount point */
           /* path is variable length and 0-terminated */
   };
   
   struct jleaf_vattr {
           int32_t modes;
           int32_t fflags;
           struct timespec atime;
           struct timespec mtime;
           struct timespec ctime;
           int64_t inum;
   };
   
   struct jleaf_cred {
           int32_t uid;
           int32_t gid;
           int32_t pid;
           int32_t flags;          /* suid/sgid and other flags */
           char    line[8];        /* ttyname or other session identification */
           char    comm[8];        /* simplified command name for reference */
   };
   
   struct jleaf_ioinfo {
           int64_t offset;
   };
   
   #endif

Cache object: 38a7ffa81a05b121c22fde599d067fa1