text: /*
   * 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
  